home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 4 / The 640 Meg Shareware Studio CD-ROM Volume IV (Data Express)(1994).ISO / clang / rxu13.zip / YDBAUTIL.INF (.txt) < prev   
OS/2 Help File  |  1993-10-26  |  72KB  |  2,774 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About YDBAUTIL ΓòÉΓòÉΓòÉ
  3.  
  4. YDBAUTIL is a package of diverse OS/2 Rexx External Functions. Some functions 
  5. in this package work with features of Extended Services (ES), although you do 
  6. not need to have ES installed to use the non-ES functions. Almost all the 
  7. functions in this package are in use in many of my own programs and are fairly 
  8. well de-bugged.  Please let me know of any problems you encounter in using the 
  9. functions, or of any suggestions for enhancements to existing functions, or 
  10. ideas for new ones. 
  11.  
  12.  
  13.   With the functions in the YDBAUTIL function package, you can make
  14.   use of some of OS/2's most powerful facilities, such as multi-threading,
  15.   processes, sessions, semaphores, shared memory, OS/2 queues, etc.
  16.   Some of these features are not only useful in pure Rexx applications,
  17.   but they allow you to write Rexx programs which can talk to compiled
  18.   programs on their level (i.e. reference memory by address, use
  19.   semaphores, etc.).
  20.  
  21.   Another benefit is the ability to quickly prototype real OS/2 programs
  22.   using real OS/2 APIs so that you can cheaply 'prove' techniques
  23.   before committing them to 'C' code.
  24.  
  25.   The capabilities provided to Rexx programs by this package, in
  26.   conjunction with those provided by other Rexx function packages
  27.   (database access, APPC, etc.) and the base language itself allow
  28.   you to prototype or build Rexx applications with much of the
  29.   functional sophistication (and complexity, unfortunately) of "real"
  30.   OS/2 applications.
  31.  
  32.   In addition to the many OS/2 API "passthrough" functions, there are
  33.   some Rexx-specific enhancements and additions.
  34.  
  35.  
  36.   Author:        Dave Boll
  37.                  (CompuServe = 74170,2016)
  38.                  IBMMAIL(USFMCFKF)
  39.   Release Date:  26 October, 1993
  40.   Version:       1.3
  41.  
  42.  
  43. ΓòÉΓòÉΓòÉ 2. Release Notes ΓòÉΓòÉΓòÉ
  44.  
  45. This release contains fixes for some minor problems and includes a few new 
  46. functions: 
  47.  
  48.   RxOpen          - open a file with full DosOpen() capabilities
  49.   RxGetInfoBlocks - get DosGetInfoBlocks() info
  50.   RxStem2Struct   - map values of a stem into a structure (finally implemented)
  51.   RxQueryAppType  - query application type of an executable file
  52.  
  53. This function package is 32-bit code and will only work on OS/2 2.x 
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 3. How to Use It ΓòÉΓòÉΓòÉ
  57.  
  58. How to register the functions: 
  59.  
  60. In order to use the functions, you have to register them with Rexx like this:
  61.  
  62.   call rxfuncadd 'rxydbautilinit','ydbautil','rxydbautilinit'
  63.   call rxydbautilinit
  64.  
  65. The .DLL "ydbautil.dll" must be in your libpath.
  66. The program "RXSRS.EXE" must be in your path in order to use the functions
  67. "RxStartRexxSession" and "RxDetachRexxPgm".
  68.  
  69.  
  70. ΓòÉΓòÉΓòÉ 4. Available External Functions ΓòÉΓòÉΓòÉ
  71.  
  72. The available functions are: 
  73.  
  74.  
  75.   Function Package utility functions
  76.   ----------------------------------
  77.   RxYdbaUtilInit        - Register all YDBAUTIL Rexx functions
  78.   RxYdbaUtilTerm        - De-Register all YDBAUTIL Rexx functions
  79.   RxYdbaUtilQuery       - Query available external function entry point names
  80.  
  81.   UPM Related
  82.   -----------
  83.   RxUpm                 - Rexx interface to UPM
  84.   RxNet                 - Rexx interface to certain NET calls
  85.                           (also some UPM-related calls)
  86.  
  87.   System-Info related
  88.   -------------------
  89.   RxProcId              - Get process' own PID and TID information
  90.   RxGetInfoBlocks       - Get information about current process/thread
  91.   RxQueryAppType        - Get information about an executable file
  92.   RxQuerySysInfo        - Invoke DosQuerySysInfo
  93.   RxPStat               - Obtain Process Status Information (like PSTAT)
  94.   RxSetError            - Set DosError settings (enable/disable HardError
  95.                           and Exception popups)
  96.   RxReplaceModule       - Replace an active .DLL or .EXE file
  97.   RxExitList            - Use DosExitList
  98.  
  99.   Rexx programming and debugging functions
  100.   ----------------------------------------
  101.   RxVlist               - List, manipulate Rexx variable pool
  102.   RxScount              - Count strings (needle) in another string (haystack)
  103.   RxPmPrintf            - Write lines to a PMPrintf Monitor
  104.   RxCallInStore         - Execute a string as a program
  105.   RxTokenize            - Tokenize ("Compile") a program string
  106.   RxPullQueue           - Pull items from any Rexx data queue
  107.   RxAddQueue            - Add items to any Rexx data queue
  108.   RxQueued              - Query number of items on any Rexx data queue
  109.   RxQExists             - Query existence of a Rexx Queue
  110.   RxSearchPath          - Find a file in a path
  111.  
  112.   I/O related
  113.   -----------
  114.   RxRsoe2f              - Redirect StdOut/StdErr to a file (by file name)
  115.   RxSoSe2H              - Redirect StdOut/StdErr to a file (by file handle)
  116.   RxSi2H                - Redirect StdIn from a file (by file handle)
  117.   RxRSi2F               - Redirect StdIn from a file (by file name)
  118.   RxOpen                - Open a file (with full DosOpen capabilities)
  119.   RxRead                - Read data from a file handle
  120.   RxWrite               - Write data to a file handle
  121.   RxCloseH              - Close a file handle
  122.   RxExecI               - Read data into a Rexx queue or stem from a file
  123.   RxExecO               - Write data from a Rexx queue or stem to a file
  124.  
  125.   OS/2 Pipes
  126.   ----------
  127.   RxCreateNPipe         - Create a named pipe
  128.   RxConnectNPipe        - Connect to a named pipe
  129.   RxDisConnectNPipe     - Disconnect from a named pipe
  130.   RxCreatePipe          - Create an un-named pipe
  131.   RxDestroyPipe         - Destroy a pipe
  132.  
  133.   OS/2 Queues
  134.   ----------
  135.   RxCreateQueue         - DosCreateQueue
  136.   RxOpenQueue           - DosOpenQueue
  137.   RxPeekQueue           - DosPeekQueue
  138.   RxReadQueue           - DosReadQueue
  139.   RxWriteQueue          - DosWriteQueue
  140.   RxPurgeQueue          - DosPurgeQueue
  141.   RxQueryQueue          - DosQueryQueue
  142.   RxCloseQueue          - DosCloseQueue
  143.   RxReadQueueStr        - Returns data from de-referenced queue pointer
  144.  
  145.   NetBios information
  146.   -------------------
  147.   RxNbSessionStatus     - Obtain NETBIOS session status information
  148.  
  149.   Tasking, threads, etc.
  150.   ----------------------
  151.   RxSetPriority         - Set the priority of processes or threads
  152.             Process - Related
  153.   RxKillProcess         - Kill an OS/2 process by process-id
  154.   RxExecPgm             - Execute a program using DosExecPgm
  155.   RxStartSession        - Start a program in another session (DosStartSession)
  156.   RxStartRexxSession    - Start a Rexx program in another session
  157.   RxDetachRexxPgm       - Detach a Rexx program
  158.             Thread - Related
  159.   RxCreateRexxThread    - Execute a Rexx program on another thread
  160.   RxCreateThread        - Call a procedure address on another thread
  161.   RxKillThread          - Kill a thread by thread-id
  162.   RxResumeThread        - Resume thread execution by thread-id
  163.   RxSuspendThread       - Suspend thread execution by thread-id
  164.   RxCallEntryPoint      - Call a (non-Rexx) routine by entry point address
  165.  
  166.   OS/2 Memory managment
  167.   ---------------------
  168.   RxStructMap           - Generate a structure map for RxStruct2Stem()
  169.   RxStruct2Stem         - Map structure elements into a stem
  170.   RxStem2Struct         - Map a stem into structure elements
  171.   RxStorage             - Query/Alter storage by address
  172.   RxAdd2Ptr             - Pointer Arithmetic (Add/Subtract)
  173.   RxAllocMem            - Allocate Memory
  174.   RxFreeMem             - Free Memory
  175.   RxAllocSharedMem      - Allocated Shared memory (named or un-named)
  176.   RxGetSharedMem        - Get (gettable) shared memory
  177.   RxGiveSharedMem       - Give (giveable) shared memory
  178.   RxGetNamedSharedMem   - Get named shared memory
  179.   RxSetMem              - Set memory attributes
  180.   RxQueryMem            - Query memory attributes
  181.   RxSubAllocMem         - Suballocate memory
  182.   RxSubFreeMem          - Free suballocated memory
  183.   RxSubSetMem           - Set memory for suballocation
  184.   RxSubUnsetMem         - Unset previously "SubSet" memory
  185.  
  186.   OS/2 Semaphores
  187.   ---------------
  188.              Event Semaphore
  189.   RxCreateEventSem      - Create an event semaphore
  190.   RxCloseEventSem       - Close an event semaphore
  191.   RxOpenEventSem        - Open an event semaphore
  192.   RxPostEventSem        - Post an event semaphore
  193.   RxQueryEventSem       - Query an event semaphore
  194.   RxResetEventSem       - Reset an event semaphore
  195.   RxWaitEventSem        - Wait on an event semaphore
  196.              Mutex Semaphore
  197.   RxCreateMutexSem      - Create a Mutex semaphore
  198.   RxOpenMutexSem        - Invoke DosOpenMutexSem
  199.   RxCloseMutexSem       - Invoke DosCloseMutexSem
  200.   RxQueryMutexSem       - Invoke DosQueryMutexSem
  201.   RxReleaseMutexSem     - Invoke DosReleaseMutexSem
  202.   RxRequestMutexSem     - Invoke DosRequestMutexSem
  203.              MuxWait Semaphore
  204.   RxCreateMuxWaitSem    - Invoke DosCreateMuxWaitSem
  205.   RxCloseMuxWaitSem     - Invoke DosCloseMuxWaitSem
  206.   RxOpenMuxWaitSem      - Invoke DosOpenMuxWaitSem
  207.   RxWaitMuxWaitSem      - Invoke DosWaitMuxWaitSem
  208.   RxAddMuxWaitSem       - Invoke DosAddMuxWaitSem
  209.   RxDeleteMuxWaitSem    - Invoke DosDeleteMuxWaitSem
  210.   RxQueryMuxWaitSem     - Invoke DosQueryMuxWaitSem
  211.  
  212.   DLL Handling
  213.   ------------
  214.   RxLoadModule          - Load a DLL
  215.   RxFreeModule          - Free a DLL
  216.   RxQueryModuleName     - Query the fully qualified name of a DLL (by handle)
  217.   RxQueryModuleHandle   - Query the module handle of a DLL (by name)
  218.   RxQueryProcType       - Query the addressing mode of an entry point in a DLL
  219.   RxQueryProcAddr       - Query the procedure address of an entry point in a DLL
  220.  
  221.   Rexx Macro Space Handling
  222.   -------------------------
  223.   RxAddMacro            - Add a particular Macro Space function
  224.   RxDropMacro           - Drop a particular Macro Space function
  225.   RxClearMacroSpace     - Clear the Rexx Macro Space
  226.   RxSaveMacroSpace      - Save a particular Macro Space function to a file
  227.   RxLoadMacroSpace      - Load a particular Macro Space function from a file
  228.   RxQueryMacro          - Query the position of a particular Macro Space function
  229.   RxReorderMacro        - Reorder a function's position in a Macro Space
  230.  
  231.   PM / Wp related functions
  232.   -------------------------
  233.   RxWinQueryObject      - Query object handle of a WP object
  234.   RxWinDestroyObject    - Destroy a WP object
  235.  
  236.  
  237. ΓòÉΓòÉΓòÉ 5. UPM Related Functions ΓòÉΓòÉΓòÉ
  238.  
  239. Functions which allow certain UPM activities to be performed. 
  240.  
  241.  
  242. ΓòÉΓòÉΓòÉ 5.1. RxUpm - Rexx/UPM Interface ΓòÉΓòÉΓòÉ
  243.  
  244. This function allows you to make most UPM calls from a Rexx program. 
  245.  
  246. Syntax:
  247.  
  248.   func  = 'Logon'     For Process level logon, only usable by that process */
  249.           'Logonp'
  250.         = 'Logonu'    For "User" logon, usable by all processes
  251.         = 'Logoff'    For Process level logoff, undoes a "LOGONP"
  252.           'Logoffp'
  253.         = 'Logoffu'   For "User" logoff, undoes a "LOGONU"
  254.         = 'LogonList' Gets list of current active logons
  255.   uid   = 'Userid'    Userid to be logged on/off
  256.         = 'stemname'  Name of Rexx stem variable under which results
  257.                       of "LogonList" are mapped as such:
  258.                       stem.0    - Number of logons reported on
  259.                       stem.n.1  - Userid
  260.                       stem.n.2  - Node/Domain name
  261.                       stem.n.3  - Session-Id
  262.                       stem.n.4  - Logon type (Local/Node/Domain)
  263.   pw    = 'Password'  Password to be used with 'Userid' (for logon)
  264.   type  = 'Local'     Logs you on/off UPM locally (default is LOCAL if
  265.                       no value supplied)
  266.         = 'Node'      Logs you on/off a node
  267.         = 'Domain'    Logs you on/off a LAN domain
  268.         = 'dataBase'  Logs you on/off the correct node for a database
  269.   name  = 'Name'      The name of the node/domain/database, depending on
  270.                       what "TYPE" was chosen
  271.   check = 'Admin'     Checks to see if userid has Admin authority
  272.         = 'User'      Checks to see if userid has User authority
  273.         = 'Config'    Checks to see if logon was done from Config.Sys
  274.  
  275.   upmrc = RxUpm(func, uid, pw, type, name, check)
  276.  
  277.  
  278. ΓòÉΓòÉΓòÉ 5.2. RxNet - Rexx/NET Interface ΓòÉΓòÉΓòÉ
  279.  
  280. This function allows you to make certain NetApi calls from Rexx.  This enables 
  281. you to do such things as changing passwords, adding and deleting userids, 
  282. validating a userid/pw, listing users and logons. 
  283.  
  284. Syntax:
  285.  
  286. /* General syntax */
  287.   netrc = RxNet(func, server, arg3, arg4, arg5, arg6)
  288.  
  289. where:
  290.  
  291.   func   = 'UserPwSet' /* Change a user's password */
  292.          = 'UserAdd'   /* Add a user to UPM */
  293.          = 'UserDel'   /* Delete a user from UPM */
  294.          = 'UserVal'   /* Validate a userid/password without logging on */
  295.          = 'UserEnum'  /* List users in UPM */
  296.          = 'LogonEnum' /* List active logons */
  297.          = 'FileEnum'  /* File usage on the LAN */
  298.          = 'UseAdd'    /* Do a "Net Use dev \\srv\alias" */
  299.          = 'UseDel'    /* Do a "Net Use dev /d" */
  300.          = 'UseEnum'   /* Do a "Net Use" */
  301.   server = name of server, or '00'x for local
  302.   netrc  = return code from NetApi call. If netrc < 2100, then it's probably
  303.            a base OS/2 return code, otherwise, it's defined in NETCONS.H
  304.  
  305. /* Specific calls */
  306.   netrc = RxNet('UserPwSet', server, userid, oldpw, newpw)
  307.  
  308.   netrc = RxNet('UserAdd', server, userid, password, type, comment)
  309.           type = 'User', 'Guest', or 'Admin'
  310.  
  311.   netrc = RxNet('UserDel', server, userid)
  312.  
  313.   netrc = RxNet('UserVal', server, userid, password)
  314.  
  315.   netrc = RxNet('UserEnum',server, rexxstem)
  316.           rexxstem = Rexx stem name, under which results are mapped as:
  317.                      stem.0 = number of users
  318.                      stem.n.1 = userid
  319.                      stem.n.2 = privilege level (Guest, User, Admin, ?)
  320.                      stem.n.3 = password age (in seconds)
  321.                      stem.n.4 = comment
  322.  
  323.   netrc = RxNet('LogonEnum',server, rexxstem)
  324.           rexxstem = Rexx stem name, under which results are mapped as:
  325.                      stem.0 = number of users
  326.                      stem.n.1 = userid
  327.  
  328.   netrc = RxNet('FileEnum',server, basepath, username, rexxstem)
  329.           basepath = file path/name qualifier
  330.           username = username qualifier
  331.           rexxstem = Rexx stem name, under which results are mapped as:
  332.                      stem.0 = number of entries
  333.                      stem.n.1 = file-id
  334.                      stem.n.2 = permissions
  335.                      stem.n.3 = numlocks
  336.                      stem.n.4 = pathname
  337.                      stem.n.5 = username
  338.  
  339.   netrc = RxNet('UseAdd', server, device, name, password)
  340.           device   = Local name for resource, such as a drive letter
  341.           name     = server\alias (must be like "\\servname\alias")
  342.           password = optional password to use resource
  343.  
  344.   netrc = RxNet('UseDel', server, device, forcemode)
  345.           device    = Local name for resource, such as a drive letter
  346.           forcemode = 'F'orce
  347.                       'N'o force
  348.                       'M'ax force
  349.  
  350.   netrc = RxNet('UseEnum',server, rexxstem)
  351.           rexxstem = Rexx stem name, under which results are mapped as:
  352.                      stem.0 = number of entries
  353.                      stem.n.1 = device name
  354.                      stem.n.2 = name
  355.                      stem.n.3 = status, values are:
  356.                                 Ok
  357.                                 Paused
  358.                                 Disconnected/SessionLost
  359.                                 NetError
  360.                                 Connecting
  361.                                 Reconnecting
  362.                                 ?
  363.                      stem.n.4 = asg_type, values are:
  364.                                 WildCard
  365.                                 DiskDevice
  366.                                 SpooledPrinter
  367.                                 SerialDevice
  368.                                 IPC (InterProcessCommunication)
  369.                                 ?
  370.                      stem.n.5 = refcount
  371.                      stem.n.5 = usecount
  372.  
  373.  
  374. ΓòÉΓòÉΓòÉ 6. Rexx Programming/Debugging ΓòÉΓòÉΓòÉ
  375.  
  376. Tools for developing Rexx programs. 
  377.  
  378.  
  379. ΓòÉΓòÉΓòÉ 6.1. RxSCount - Count instances of a string ΓòÉΓòÉΓòÉ
  380.  
  381. This function returns a count of the number of instances of a string "needle" 
  382. in a string "haystack", optionally ignoring case. 
  383.  
  384. Syntax:
  385.  
  386.   numitem = rxscount(needle,haystack[,case])
  387.  
  388. where:
  389.  
  390.   needle   = string you want to count instances of
  391.   haystack = string in which you want to count instances of "needle"
  392.   case     = any character to indicate that case (upper/lower) is to
  393.              be ignored
  394.   numitem  = number of times "needle" is found in "haystack"
  395.  
  396.  
  397. ΓòÉΓòÉΓòÉ 6.2. RxPmPrintf - Write lines to a PMPrintf Monitor ΓòÉΓòÉΓòÉ
  398.  
  399. This function writes data lines to a PMPrintf "Monitor" program. 
  400.  
  401. Syntax:
  402.  
  403.   bytes = RxPmPrintf(qname, [data1 [,data2 [,data3 [...]]]] )
  404.  
  405. where:
  406.  
  407.   qname    = name of PMPrintf queue
  408.              If blank, uses default PMPrintf Queue (PRINTF32).
  409.   data1    = data to be written to PMPrintf
  410.   ...        Each argument is written as a separate line
  411.   datan
  412.  
  413.   bytes    = number of bytes written in this operation
  414.  
  415. Notes:
  416.  
  417.   The PMPrintf tool can be downloaded from the OS/2 Bulletin Board.
  418.   This Rexx function does work with PMPrintf v2.5, but may not work
  419.   with earlier versions.  You can start the PMPrintf program with
  420.   a command line argument specifying an alternate queue name for it
  421.   to use.  This queue name can be supplied as the first argument of
  422.   RxPmPrintf to direct the data to a specific running instance of
  423.   PMPrintf.
  424.  
  425.   If only the queue name is supplied (i.e. args 2-n are not supplied),
  426.   nothing at all is written to queue.  If an argument has zero length,
  427.   no data will be written to the queue for that argument (i.e. you
  428.   must supply at least one byte to be written to queue).
  429.  
  430.  
  431. ΓòÉΓòÉΓòÉ 6.3. RxCallInStore - Execute a string as a program ΓòÉΓòÉΓòÉ
  432.  
  433. This function allows the Rexx program developer to execute a string as though 
  434. it were a Rexx program.  This allows you to build the equivalent of a Rexx 
  435. program's text in a variable, and then execute it from the string.  Actually, 
  436. the Rexx program text can come from anywhere -- a file, over a communications 
  437. link, from a database. For repeated execution of a program, use "RxTokenize" to 
  438. "compile" the program, then call "RxCallInStore" with "&" to re-use the 
  439. tokenized program. 
  440.  
  441. Syntax:
  442.  
  443.   result = RxCallInStore strtext, arg1, arg2, ..., arg19
  444.  
  445. where:
  446.  
  447.   strtext  = text of a Rexx program, complete with crlf and eof markers
  448.                   or
  449.              a '$' immediately preceding a source program string
  450.                   or
  451.              a '&' immediately preceding a tokenized program string
  452.   arg1     = arguments to the called program
  453.   ...
  454.   arg19
  455.  
  456. Note:
  457.  
  458.   Example of executing a program string:
  459.  
  460.     crlf = '0d0a'x
  461.     str = '/* Rexx */'crlf
  462.     str = str 'Do i=1 To Arg()'crlf
  463.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  464.     str = str 'End'crlf
  465.     str = str||'1a'x       /* EOF marker */
  466.     call rxcallinstore str, date(), time()
  467.                ( or )
  468.     call rxcallinstore '$'str, date(), time()
  469.                ( or )
  470.     tstr = rxtokenize(str)
  471.     call rxcallinstore '&'tstr, date(), time()
  472.  
  473.  
  474. ΓòÉΓòÉΓòÉ 6.4. RxTokenize - Tokenize a program source string ΓòÉΓòÉΓòÉ
  475.  
  476. This function in effect "compiles" a program source string for re-use with 
  477. subsequent "RxCallInstore" or "RxCreateRexxThread" calls. This provides better 
  478. performance when a program string is repeatedly called. 
  479.  
  480. Syntax:
  481.  
  482.   tokenstr = RxTokenize(progstr)
  483.  
  484. where:
  485.  
  486.   progstr  = actual Rexx program source string
  487.   tokenstr = tokenized ("compiled") result of "progstr"
  488.  
  489. Note:
  490.  
  491.   This function, in conjunction with the "RxCallInstore" and/or
  492.   "RxCreateRexxThread" functions, can be used to achieve the same
  493.   effect as the Rexx Macrospace, except that this technique is local
  494.   to the program using it (whereas the Macrospace is system global).
  495.  
  496.  
  497. ΓòÉΓòÉΓòÉ 6.5. RxVlist - Display/Process Rexx Variables ΓòÉΓòÉΓòÉ
  498.  
  499. This function allows the Rexx program developer to view portions of the Rexx 
  500. variable pool.  It also allows you to effectively "pass" variable pools (or 
  501. subsets thereof) between execs across Rexx queues. 
  502.  
  503. Syntax:
  504.  
  505.   numvar = RxVlist( [vnamepat] [,func] [,qname] )
  506.  
  507. where:
  508.  
  509.   func     = 'V'  /* Puts variable name/value pairs on a queue */
  510.            = 'N'  /* Puts variable names on a queue */
  511.            = 'G'  /* Gets variable name/value pairs off a queue */
  512.                   /* and incorporates them into the current variable pool */
  513.            = 'D'  /* display variables and their values (default) */
  514.   vnamepat = variable name prefix (every variable whose name begins with this
  515.              value is processed according to the specified function)
  516.              (default is all variables)
  517.   qname    = name of a Rexx queue to use (default is the current queue)
  518.  
  519.  
  520. ΓòÉΓòÉΓòÉ 6.6. RxPullQueue - Pull items off any Rexx queue ΓòÉΓòÉΓòÉ
  521.  
  522. This function does what the Rexx "Pull" instruction and "LineIn" functions do, 
  523. except this function allows you to specify the queue name as part of the call, 
  524. regardless of what the current queue may be. 
  525.  
  526. Syntax:
  527.  
  528.   data = RxPullQueue( [qname] [,type] [,rexxvar] )
  529.  
  530. where:
  531.  
  532.   qname   = name of Rexx queue to pull from (default is current queue)
  533.   type    = 'Wait' or 'Nowait' (default is 'Wait')
  534.   rexxvar = name of a Rexx variable into which is put the queue-insertion-
  535.             timestamp for the retreived element
  536.   data    = data obtained from queue
  537.  
  538.  
  539. ΓòÉΓòÉΓòÉ 6.7. RxAddQueue - Add items to any Rexx queue ΓòÉΓòÉΓòÉ
  540.  
  541. This function does what the Rexx "Queue" and "Push" instructions, and the 
  542. "LineOut" function do, except this function allows you to specify the queue 
  543. name as part of the call, regardless of what the current queue may be. 
  544.  
  545. Syntax:
  546.  
  547.   qrc = RxAddQueue( data [,qname] [,type] )
  548.  
  549. where:
  550.  
  551.   data  = data to be placed on queue
  552.   qname = name of Rexx queue to add to (default is current queue)
  553.   type  = 'Queue' or 'Push' (default is 'Queue')
  554.  
  555.  
  556. ΓòÉΓòÉΓòÉ 6.8. RxQueued - Query number of items on any Rexx queue ΓòÉΓòÉΓòÉ
  557.  
  558. This function does what the Rexx "Queued" function does, except this function 
  559. allows you to specify the queue name as part of the call, regardless of what 
  560. the current queue may be. 
  561.  
  562. Syntax:
  563.  
  564.   numq = RxQueued( [qname] )
  565.  
  566. where:
  567.  
  568.   qname = name of Rexx queue to report on (default is current queue)
  569.  
  570.  
  571. ΓòÉΓòÉΓòÉ 6.9. RxQExists - Query existence of a Rexx Queue ΓòÉΓòÉΓòÉ
  572.  
  573. This function returns "1" or "0", indicating the existence of the Rexx Queue 
  574. whose name you supply as an argument. 
  575.  
  576. Syntax:
  577.  
  578.   bool = RxQExists( [qname] )
  579.  
  580. where:
  581.  
  582.   qname = name of Rexx queue to check for existence of
  583.   bool  = truth value of queue's existence
  584.  
  585.  
  586. ΓòÉΓòÉΓòÉ 6.10. RxSearchPath - Find a file in a path ΓòÉΓòÉΓòÉ
  587.  
  588. This function does what REXXUTIL's "SysSearchPath" does, but allows full use of 
  589. DosSearchPath capabilities. 
  590.  
  591. Syntax:
  592.  
  593.   info = RxSearchPath(fname,path[,flags])
  594.  
  595. where:
  596.  
  597.   fname = name of file to search for (can contain pattern characters)
  598.   path  = either an actual path string, or the name of an environment
  599.           variable containing a path string
  600.   flags = any combination of:
  601.           V - indicates that "path" is an environment variable name,
  602.               rather than an actual path string
  603.           I - ignore network errors when searching through network
  604.               drives
  605.           C - search current directory first
  606.           The default is "Not V, Not I, Not C".
  607.   info  = two blank delimited tokens:
  608.           1) return code from DosSearchPath
  609.           2) If (1) is zero, the fully qualified name of the file found
  610.  
  611.  
  612. ΓòÉΓòÉΓòÉ 7. Memory Management/Access ΓòÉΓòÉΓòÉ
  613.  
  614. These functions allow Rexx programs to create, access, and manage OS/2 memory 
  615. objects by address.  This includes objects such as shared memory (named and 
  616. un-named). 
  617.  
  618.  
  619. ΓòÉΓòÉΓòÉ 7.1. RxStructMap - Generate a structure map for RxStruct2Stem() ΓòÉΓòÉΓòÉ
  620.  
  621. This function builds a "structure map" which can be used by the function 
  622. RxStruct2Stem() to map the elements of a structure into a Rexx stem.  The 
  623. elements of the structure must be described by the Rexx program.  This can be 
  624. used to access the elements of a structure whose address is passed to the Rexx 
  625. program by a compiled program. 
  626.  
  627. Syntax:
  628.  
  629.   map = RxStructMap(stemname)
  630.  
  631. where
  632.  
  633.   stemname = name of Rexx stem under which structure is described as such:
  634.  
  635.              stem.0   = Number of elements in structure (1-n)
  636.              stem.P   = Packing mode of structure (default = 1)
  637.              stem.n.T = Type of element "n" in structure.  Valid
  638.                         values are:
  639.                         l = signed long integer    (4 bytes)
  640.                         L = unsigned long integer  (4 bytes)
  641.                         s = signed short integer   (2 bytes)
  642.                         S = unsigned short integer (2 bytes)
  643.                         d = double                 (8 bytes)
  644.                         D = double                 (8 bytes)
  645.                         c = character array        (stem.n.L bytes)
  646.                         C = character array        (stem.n.L bytes)
  647.              stem.n.L = Length of character array (if type = 'C'
  648.                         or 'c')
  649.  
  650.   map      = binary structure map used by RxStruct2Stem()
  651.  
  652.  
  653. ΓòÉΓòÉΓòÉ 7.2. RxStruct2Stem - Map structure elements into a stem ΓòÉΓòÉΓòÉ
  654.  
  655. This function allows a Rexx program to map the elements of a structure into a 
  656. Rexx stem.  The structure is referred to by its address.  The structure is 
  657. described by the map built with RxStructMap().  This can be used to access the 
  658. elements of a structure whose address is passed to the Rexx program by a 
  659. compiled program. 
  660.  
  661. Syntax:
  662.  
  663.   bytes = RxStruct2Stem(stemname, pointer, map)
  664.  
  665. where
  666.  
  667.   stemname = name of Rexx stem under which structure elements' values
  668.              are returned, as such:
  669.  
  670.              stem.0   = Number of elements in structure
  671.              stem.n   = Actual value of element "n" in structure
  672.  
  673.   pointer  = 32-bit pointer (address) to base of structure
  674.   map      = structure map generated by RxStructMap()
  675.   bytes    = total number of bytes in structure
  676.  
  677.  
  678. ΓòÉΓòÉΓòÉ 7.3. RxStem2Struct - Map a stem into structure elements ΓòÉΓòÉΓòÉ
  679.  
  680. This function allows a Rexx program to map a stem variable into the elements of 
  681. a structure.  The structure is referred to by its address. 
  682.  
  683.  
  684. Syntax:
  685.  
  686.   bytes = RxStem2Struct(stemname, pointer, map)
  687.  
  688. where
  689.  
  690.   stemname = name of Rexx stem under which structure elements' values
  691.              are provided, as such:
  692.  
  693.              stem.n   = Actual value of element "n" in structure
  694.  
  695.   pointer  = 32-bit pointer (address) to base of structure
  696.   map      = structure map generated by RxStructMap()
  697.   bytes    = total number of bytes in structure
  698.  
  699.  
  700. ΓòÉΓòÉΓòÉ 7.4. RxStorage - Access/Alter memory by address ΓòÉΓòÉΓòÉ
  701.  
  702. This function allows a Rexx program to access and/or alter storage by address. 
  703. This could be used to process data passed to it by a program.  This could also 
  704. be used to "Pass By Reference" among Rexx programs when using the RxAllocMem 
  705. and RxFreeMem functions. 
  706.  
  707. Syntax:
  708.  
  709.   outdata = RxStorage( pointer [, length] [, indata] )
  710.  
  711. where
  712.  
  713.   pointer  = 32-bit pointer (address)
  714.   length   = Length of storage to be queried (defaults to 1)
  715.   indata   = Data to place at address "pointer" for the length of the data
  716.              (regardless of "length" value)
  717.   outdata  = Data at address "pointer" for length "length" (truncated if
  718.              "length" takes you beyond allowed storage)
  719.  
  720. Note:
  721.  
  722.   A request to query memory out-of-bounds returns a string up to the bound-
  723.   ary.  A request to set memory out-of-bounds, sets memory up to the bound-
  724.   ary.  All memory is allocated in 4k chunks.  Therefore, some query or set
  725.   operations will access memory up to the next 4k boundary.
  726.  
  727.  
  728. ΓòÉΓòÉΓòÉ 7.5. RxAdd2Ptr - Pointer Arithmetic (Add/Subtract) ΓòÉΓòÉΓòÉ
  729.  
  730. This function allows a Rexx program to add or subtract from an OS/2 32-bit 
  731. linear address. 
  732.  
  733. Syntax:
  734.  
  735.   newptr = RxAdd2Ptr( pointer , [number] )
  736.  
  737. where:
  738.  
  739.   pointer  = 32-bit pointer (address)
  740.   number   = amount by which "pointer" is to be incremented/decremented
  741.              in bytes.  Default is zero.
  742.   newptr   = result of addition/subtraction
  743.  
  744.  
  745. ΓòÉΓòÉΓòÉ 7.6. RxAllocMem - Allocate memory (using DosAllocMem) ΓòÉΓòÉΓòÉ
  746.  
  747. This function allows a Rexx program to allocate memory.  This memory can then 
  748. be accessed using RxStorage. 
  749.  
  750. Syntax:
  751.  
  752.   allocrc = RxAllocMem(rexxvar, length, flags)
  753.  
  754. where
  755.  
  756.   rexxvar = name of a rexx variable in which pointer is returned
  757.   length  = a decimal integer indicating amount of storage (in bytes) to
  758.             allocate
  759.   flags   = any combination of:
  760.             C - Pag_Commit
  761.             T - Obj_Tile
  762.             X - Pag_Execute
  763.             R - Pag_Read
  764.             W - Pag_Write
  765.             G - Pag_Guard
  766.   allocrc = return code from DosAllocMem()
  767.  
  768. for example:
  769.             /* Following would get 4k committed read/write */
  770.   allocrc = RxAllocMem('pointer', 4096, 'crw')
  771.  
  772. Note:
  773.  
  774.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  775.   bytes, you will get access to 4096 bytes.
  776.  
  777.  
  778. ΓòÉΓòÉΓòÉ 7.7. RxFreeMem - Free memory allocated by RxAllocMem ΓòÉΓòÉΓòÉ
  779.  
  780. This function allows a Rexx program to free memory allocated by RxAllocMem. 
  781.  
  782. Syntax:
  783.  
  784.   freerc = RxFreeMem(pointer)
  785.  
  786. where
  787.  
  788.   pointer - A valid 32 bit pointer.
  789.  
  790. Note:
  791.  
  792.   Returned value is return code from DosFreeMem
  793.  
  794.  
  795. ΓòÉΓòÉΓòÉ 7.8. RxAllocSharedMem - Allocate shared memory ΓòÉΓòÉΓòÉ
  796.  
  797. This function allocates shared (named or un-named) memory.  Other processes can 
  798. access this memory with either RxGetSharedMem (un-named), or 
  799. RxGetNamedSharedMem (named), or if it is "Given", followed by calls to 
  800. RxStorage. 
  801.  
  802. Syntax:
  803.  
  804.   allocrc = RxAllocSharedMem(rexxvar, length, flags [,memname] )
  805.  
  806. where
  807.  
  808.   rexxvar = name of a rexx variable in which pointer is returned
  809.   length  = a decimal integer indicating amount of storage (in bytes) to
  810.             allocate
  811.   flags   = any combination of:
  812.             C - Pag_Commit
  813.             T - Obj_Tile
  814.             I - Obj_Giveable
  815.             E - Obj_Gettable (sic)
  816.             X - Pag_Execute
  817.             R - Pag_Read
  818.             W - Pag_Write
  819.             G - Pag_Guard
  820.   memname = name of shared memory object, if this is to be named shared
  821.             memory
  822.   allocrc = return code from DosAllocSharedMem()
  823.  
  824. for example:
  825.  
  826.   /* To allocate an un-named, gettable object */
  827.   allocrc = RxAllocSharedMem('pointer', 4096, 'cerw')
  828.  
  829.   /* To allocate a named object */
  830.   allocrc = RxAllocSharedMem('pointer', 4096, 'crw','\SHAREMEM\TEST.MEM')
  831.  
  832. Note:
  833.  
  834.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  835.   bytes, you will get access to 4096 bytes.
  836.  
  837.  
  838. ΓòÉΓòÉΓòÉ 7.9. RxGiveSharedMem - Give access to shared memory ΓòÉΓòÉΓòÉ
  839.  
  840. This function gives access to shared, un-named memory to a process-id 
  841.  
  842. Syntax:
  843.  
  844.   giverc = RxGiveSharedMem(pointer, pid [,flags])
  845.  
  846. where
  847.  
  848.   pointer = valid 32-bit pointer
  849.   pid     = valid process-id (as a decimal integer)
  850.   flags   = any combination of:
  851.             X - Pag_Execute
  852.             R - Pag_Read
  853.             W - Pag_Write
  854.             G - Pag_Guard
  855.  
  856. for example:
  857.  
  858.   /* To give shared memory */
  859.   giverc = RxGiveSharedMem(pointer, 23, 'rw')
  860.  
  861. Note:
  862.  
  863.   A valid pointer must be supplied.  This is obtained from the process which
  864.   allocated the shared un-named memory via RxAllocSharedMem.  The process-id
  865.   supplied must be valid (i.e. must currently exist).
  866.  
  867.  
  868. ΓòÉΓòÉΓòÉ 7.10. RxGetSharedMem - Get access to shared memory ΓòÉΓòÉΓòÉ
  869.  
  870. This function gets access to shared, un-named, gettable memory. 
  871.  
  872. Syntax:
  873.  
  874.   getrc = RxGetSharedMem(pointer, flags)
  875.  
  876. where
  877.  
  878.   pointer = valid 32-bit pointer
  879.   flags   = any combination of:
  880.             X - Pag_Execute
  881.             R - Pag_Read
  882.             W - Pag_Write
  883.             G - Pag_Guard
  884.  
  885. for example:
  886.  
  887.   /* To get shared memory */
  888.   getrc = RxGetSharedMem(pointer, 'rw')
  889.  
  890. Note:
  891.  
  892.   A valid pointer must be supplied.  This is obtained from the process which
  893.   allocated the shared un-named memory via RxAllocSharedMem.
  894.  
  895.  
  896. ΓòÉΓòÉΓòÉ 7.11. RxGetNamedSharedMem - Get access to named shared memory ΓòÉΓòÉΓòÉ
  897.  
  898. This function gets access to shared, named memory. 
  899.  
  900. Syntax:
  901.  
  902.   getrc = RxGetNamedSharedMem(rexxvar, memname, flags)
  903.  
  904. where
  905.  
  906.   rexxvar = name of a rexx variable in which pointer is returned
  907.   memname = valid name of a shared memory object
  908.   flags   = any combination of:
  909.             X - Pag_Execute
  910.             R - Pag_Read
  911.             W - Pag_Write
  912.             G - Pag_Guard
  913.   getrc   = return code from DosGetNamedSharedMem()
  914.  
  915. for example:
  916.  
  917.   /* To get named shared memory */
  918.   getrc = RxGetNamedSharedMem('pointer', '\SHAREMEM\TEST.MEM', 'rw')
  919.  
  920.  
  921. ΓòÉΓòÉΓòÉ 7.12. RxSetMem - Set memory attributes ΓòÉΓòÉΓòÉ
  922.  
  923. This function sets memory attributes using DosSetMem 
  924.  
  925. Syntax:
  926.  
  927.   setrc = RxSetMem(pointer [,memsize [,flags]])
  928.  
  929. where
  930.  
  931.   pointer = valid 32-bit pointer
  932.   memsize = size of memory block to set
  933.   flags   = any combination of:
  934.             C - Pag_Commit
  935.             D - Pag_Decommit
  936.             F - Pag_Default
  937.             X - Pag_Execute
  938.             R - Pag_Read
  939.             W - Pag_Write
  940.             G - Pag_Guard
  941.  
  942. for example:
  943.  
  944.   /* To set memory attributes */
  945.   setrc = RxSetMem(pointer, 4096, 'crw')
  946.  
  947. Note:
  948.  
  949.   Returned value is return code from DosSetMem.
  950.  
  951.  
  952. ΓòÉΓòÉΓòÉ 7.13. RxQueryMem - Query memory attributes ΓòÉΓòÉΓòÉ
  953.  
  954. This function queries memory attributes using DosQueryMem 
  955.  
  956. Syntax:
  957.  
  958.   qinfo = RxQueryMem(pointer [,memsize])
  959.  
  960. where
  961.  
  962.   pointer = valid 32-bit pointer
  963.   memsize = size of memory block to query
  964.   qinfo   = either one or three blank-delimited tokens:
  965.             1) return code from DosQueryMem
  966.                If #1 is zero:
  967.                  2) actual memory size
  968.                  3) memory attribute flags, which can be any combination of:
  969.                     C - Pag_Commit
  970.                     F - Pag_Free
  971.                     S - Pag_Shared
  972.                     B - Pag_Base
  973.                     X - Pag_Execute
  974.                     R - Pag_Read
  975.                     W - Pag_Write
  976.                     G - Pag_Guard
  977.  
  978. for example:
  979.  
  980.   /* To query memory attributes */
  981.   qinfo = RxQueryMem(pointer, 4096)
  982.   /* "Say qinfo" might say -> "0 4096 CSRW" for instance */
  983.  
  984. Note:
  985.  
  986.   If first token is not zero, no other information was returned.
  987.  
  988.  
  989. ΓòÉΓòÉΓòÉ 7.14. RxSubSetMem - Set memory for suballocation ΓòÉΓòÉΓòÉ
  990.  
  991. This function sets memory for suballocation using DosSubSetMem 
  992.  
  993. Syntax:
  994.  
  995.   subsetrc = RxSubSetMem(pointer [,memsize [,flags]])
  996.  
  997. where
  998.  
  999.   pointer = valid 32-bit pointer to pool
  1000.   memsize = size of memory block to subset
  1001.   flags   = any combination of:
  1002.             I - DosSub_Init
  1003.             G - DosSub_Grow
  1004.             S - DosSub_Sparse
  1005.             R - DosSub_Serialize
  1006.  
  1007. for example:
  1008.  
  1009.   /* To subset some memory */
  1010.   subsetrc = RxSubSetMem(pointer, 4096, 'i')
  1011.  
  1012. Note:
  1013.  
  1014.   Returned value is return code from DosSubSetMem.
  1015.  
  1016.  
  1017. ΓòÉΓòÉΓòÉ 7.15. RxSubUnSetMem - UnSet memory from suballocation ΓòÉΓòÉΓòÉ
  1018.  
  1019. This function unsets memory from suballocation using DosSubUnSetMem 
  1020.  
  1021. Syntax:
  1022.  
  1023.   subunsetrc = RxSubUnSetMem(pointer)
  1024.  
  1025. where
  1026.  
  1027.   pointer = valid 32-bit pointer to pool
  1028.  
  1029. for example:
  1030.  
  1031.   /* To subunset some memory */
  1032.   subunsetrc = RxSubUnSetMem(pointer)
  1033.  
  1034. Note:
  1035.  
  1036.   Returned value is return code from DosSubUnSetMem.
  1037.  
  1038.  
  1039. ΓòÉΓòÉΓòÉ 7.16. RxSubAllocMem - Suballocate memory ΓòÉΓòÉΓòÉ
  1040.  
  1041. This function suballocates memory. 
  1042.  
  1043. Syntax:
  1044.  
  1045.   subarc = RxSubAllocMem(rexxvar, pointer [,memsize])
  1046.  
  1047. where
  1048.  
  1049.   rexxvar = name of a rexx variable in which block offset is returned
  1050.   pointer = valid 32-bit pointer to pool
  1051.   memsize = size of block to suballocate
  1052.   subarc  = return code from DosSubAllocMem()
  1053.  
  1054. for example:
  1055.  
  1056.   /* To suballocate some memory */
  1057.   subarc = RxSubAllocMem('block_offset', pointer, 4096)
  1058.  
  1059.  
  1060. ΓòÉΓòÉΓòÉ 7.17. RxSubFreeMem - Free suballocated memory ΓòÉΓòÉΓòÉ
  1061.  
  1062. This function frees suballocated memory. 
  1063.  
  1064. Syntax:
  1065.  
  1066.   freerc = RxSubFreeMem(pointer, boffset [,memsize])
  1067.  
  1068. where
  1069.  
  1070.   pointer = valid 32-bit pointer to pool
  1071.   boffset = block offset pointer
  1072.   memsize = size of block to free
  1073.  
  1074. for example:
  1075.  
  1076.   /* To free suballocated memory */
  1077.   freerc = RxSubFreeMem(pointer, boffset, 4096)
  1078.  
  1079. Note:
  1080.  
  1081.   Returned value is return code from DosSubFreeMem.
  1082.  
  1083.  
  1084. ΓòÉΓòÉΓòÉ 8. Sempahore handling ΓòÉΓòÉΓòÉ
  1085.  
  1086. These functions allow Rexx programs to make use of OS/2 semaphores for 
  1087. synchronization/serialization purposes. 
  1088.  
  1089.  
  1090. ΓòÉΓòÉΓòÉ 8.1. RxCreateEventSem - Create an event semaphore ΓòÉΓòÉΓòÉ
  1091.  
  1092. This function creates a (named or un-named) event semaphore. 
  1093.  
  1094. Syntax:
  1095.  
  1096.   semrc = RxCreateEventSem(rexxvar [,type] [,name] [,state] )
  1097.  
  1098. where
  1099.  
  1100.   rexxvar = name of a rexx variable in which sem handle is returned
  1101.   type    = 'Shared' or 'Private' (default is Private)
  1102.   name    = semaphore name (default is un-named)
  1103.   state   = 'Reset' or 'Posted' (default is Reset)
  1104.   semrc   = return code from DosCreateEventSem()
  1105.  
  1106.  
  1107. ΓòÉΓòÉΓòÉ 8.2. RxOpenEventSem - Open an event semaphore ΓòÉΓòÉΓòÉ
  1108.  
  1109. This function opens an event semaphore for use by a process that did not create 
  1110. the semaphore. 
  1111.  
  1112. Syntax:
  1113.  
  1114.   semrc = RxOpenEventSem(rexxvar, semid)
  1115.  
  1116. where
  1117.  
  1118.   rexxvar = name of a rexx variable in which sem handle is returned
  1119.   semid   = either a semaphore handle, or a semaphore name
  1120.   semrc   = return code from DosOpenEventSem()
  1121.  
  1122. Note:
  1123.  
  1124.   A zero length string is returned if DosOpenEventSem fails.
  1125.  
  1126.  
  1127. ΓòÉΓòÉΓòÉ 8.3. RxPostEventSem - Post an event semaphore ΓòÉΓòÉΓòÉ
  1128.  
  1129. This function posts an event semaphore. 
  1130.  
  1131. Syntax:
  1132.  
  1133.   postrc = RxPostEventSem(hev)
  1134.  
  1135. where
  1136.  
  1137.   hev    = semaphore handle
  1138.   postrc = return code from DosPostEventSem
  1139.  
  1140.  
  1141. ΓòÉΓòÉΓòÉ 8.4. RxQueryEventSem - Query an event semaphore ΓòÉΓòÉΓòÉ
  1142.  
  1143. This function returns the post count for an event semaphore. 
  1144.  
  1145. Syntax:
  1146.  
  1147.   info = RxQueryEventSem(hev)
  1148.  
  1149. where
  1150.  
  1151.   hev    = semaphore handle
  1152.   info   = return code from DosQueryEventSem, followed by number of posts
  1153. Note:
  1154.  
  1155.   Word 1 of info is the return code from DosQueryEventSem
  1156.   Word 2 of info is the actual number of posts to the semaphore
  1157.  
  1158.  
  1159. ΓòÉΓòÉΓòÉ 8.5. RxResetEventSem - Reset an event semaphore ΓòÉΓòÉΓòÉ
  1160.  
  1161. This function resets an event semaphore, returning the number of postings for 
  1162. that semaphore. 
  1163.  
  1164. Syntax:
  1165.  
  1166.   info = RxResetEventSem(hev)
  1167.  
  1168. where
  1169.  
  1170.   hev    = semaphore handle
  1171.   info   = return code from DosResetEventSem, followed by number of posts
  1172.  
  1173. Note:
  1174.  
  1175.   Word 1 of info is the return code from DosResetEventSem
  1176.   Word 2 of info is the actual number of posts to the semaphore before
  1177.                     the Reset.
  1178.  
  1179.  
  1180. ΓòÉΓòÉΓòÉ 8.6. RxWaitEventSem - Wait on an event semaphore ΓòÉΓòÉΓòÉ
  1181.  
  1182. This function waits on the posting of an event semaphore. 
  1183.  
  1184. Syntax:
  1185.  
  1186.   semhandle /* A valid semaphore handle */
  1187.   time = 1000   /* in milliseconds */
  1188.  
  1189.   waitrc = RxWaitEventSem(hev [,time])
  1190.  
  1191. where
  1192.  
  1193.   hev    = semaphore handle
  1194.   time   = number of miliseconds to wait before returning, or the word
  1195.            'Indefinite'.  Default is 'Indefinite'.
  1196.   waitrc = return code from DosWaitEventSem
  1197.  
  1198.  
  1199. ΓòÉΓòÉΓòÉ 8.7. RxCloseEventSem - Close an event semaphore ΓòÉΓòÉΓòÉ
  1200.  
  1201. This function closes an event semaphore 
  1202.  
  1203. Syntax:
  1204.  
  1205.   closerc = RxCloseEventSem(hev)
  1206.  
  1207. where
  1208.  
  1209.   hev     = semaphore handle
  1210.   closerc = return code from DosCloseEventSem
  1211.  
  1212.  
  1213. ΓòÉΓòÉΓòÉ 8.8. RxCreateMutexSem - Create a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1214.  
  1215. This function creates a mutex semaphore 
  1216.  
  1217. Syntax:
  1218.  
  1219.   semrc = RxCreateMutexSem(rexxvar [,type] [,name] [,state] )
  1220.  
  1221. where
  1222.  
  1223.   rexxvar = name of a rexx variable in which sem handle is returned
  1224.   type    = 'Shared' or 'Private' (default is 'Private')
  1225.   name    = semaphore name (default is un-named)
  1226.   state   = 'Owned' or 'Unowned' (default is un-owned)
  1227.   semrc   = return code from DosCreateMutexSem()
  1228.  
  1229.  
  1230. ΓòÉΓòÉΓòÉ 8.9. RxOpenMutexSem - Open a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1231.  
  1232. This function opens a mutex semaphore 
  1233.  
  1234. Syntax:
  1235.  
  1236.   semrc = RxOpenMutexSem(rexxvar, semid )
  1237.  
  1238. where
  1239.  
  1240.   rexxvar = name of a rexx variable in which sem handle is returned
  1241.   semid   = either a semaphore name, or an existing mutex semaphore handle
  1242.   semrc   = return code from DosOpenMutexSem()
  1243.  
  1244.  
  1245. ΓòÉΓòÉΓòÉ 8.10. RxCloseMutexSem - Close a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1246.  
  1247. This function closes a mutex semaphore 
  1248.  
  1249. Syntax:
  1250.  
  1251.   mtxrc = RxCloseMutexSem( hmtx )
  1252.  
  1253. where
  1254.  
  1255.   hmtx  = existing mutex semaphore handle
  1256.   mtxrc = return code from DosCloseMutexSem
  1257.  
  1258.  
  1259. ΓòÉΓòÉΓòÉ 8.11. RxQueryMutexSem - Query Mutex Semaphore ΓòÉΓòÉΓòÉ
  1260.  
  1261. This function queries a mutex semaphore's attributes 
  1262.  
  1263. Syntax:
  1264.  
  1265.   mtxinfo = RxQueryMutexSem( hmtx )
  1266.  
  1267. where
  1268.  
  1269.   hmtx    = existing mutex semaphore handle
  1270.   mtxinfo = four blank delimited tokens:
  1271.             1) return code from DosQueryMutexSem
  1272.             2) Process-Id of semaphore's current owner
  1273.             3) Thread-Id of semaphore's current owner
  1274.             4) A count of the number of calls to DosRequestMutexSem,
  1275.                minus the number of calls to DosReleaseMutexSem, that have
  1276.                been made for the semaphore by the owning thread.
  1277.                If the semaphore is unowned, this value will be zero.
  1278.                If the owning thread has ended, the value will be the
  1279.                request count for the ended owner.
  1280.  
  1281.  
  1282. ΓòÉΓòÉΓòÉ 8.12. RxReleaseMutexSem - Release Mutex Semaphore ΓòÉΓòÉΓòÉ
  1283.  
  1284. This function releases a mutex semaphore 
  1285.  
  1286. Syntax:
  1287.  
  1288.   mtxrc = RxReleaseMutexSem( hmtx )
  1289.  
  1290. where
  1291.  
  1292.   hmtx  = existing mutex semaphore handle
  1293.   mtxrc = return code from DosReleaseMutexSem
  1294.  
  1295.  
  1296. ΓòÉΓòÉΓòÉ 8.13. RxRequestMutexSem - Request Mutex Semaphore ΓòÉΓòÉΓòÉ
  1297.  
  1298. This function requests a mutex semaphore 
  1299.  
  1300. Syntax:
  1301.  
  1302.   mtxrc = RxRequestMutexSem( hmtx [, timeout] )
  1303.  
  1304. where
  1305.  
  1306.   hmtx    = existing mutex semaphore handle
  1307.   timeout = either a decimal integer (miliseconds to block), or the word
  1308.             'Indefinite'
  1309.   mtxrc   = return code from DosRequestMutexSem
  1310.  
  1311.  
  1312. ΓòÉΓòÉΓòÉ 8.14. RxCreateMuxWaitSem - Create a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1313.  
  1314. This function creates a muxwait semaphore 
  1315.  
  1316. Syntax:
  1317.  
  1318.   semrc = RxCreateMuxWaitSem(rexxvar, stemname [,type] [,anyall]
  1319.                              [,name] )
  1320.  
  1321. where
  1322.  
  1323.   rexxvar  = name of a rexx variable in which sem handle is returned
  1324.   stemname = a Rexx stem name (ending in a period '.'), under which are
  1325.              supplied the semaphore handles which constitute this muxwait
  1326.              semaphore.  The expected structure of the stem is:
  1327.              1) stem.0   = a decimal integer indicating how many semaphores
  1328.                            are supplied
  1329.              2) stem.n.1 = handle of Nth semaphore
  1330.              3) stem.n.2 = decimal integer used as an Id for Nth semaphore
  1331.   type     = 'Shared' or 'Private' (default is 'Private')
  1332.   anyall   = 'anY' or 'alL' (default is 'All')
  1333.   name     = semaphore name (default is un-named)
  1334.   semrc    = return code from DosCreateMuxWaitSem()
  1335.  
  1336.  
  1337. ΓòÉΓòÉΓòÉ 8.15. RxOpenMuxWaitSem - Open a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1338.  
  1339. This function opens a muxwait semaphore 
  1340.  
  1341. Syntax:
  1342.  
  1343.   semrc = RxOpenMuxWaitSem(rexxvar, semid )
  1344.  
  1345. where
  1346.  
  1347.   rexxvar = name of a rexx variable in which sem handle is returned
  1348.   semid   = either a semaphore name, or an existing muxwait
  1349.             semaphore handle
  1350.   semrc   = return code from DosOpenMuxWaitSem()
  1351.  
  1352.  
  1353. ΓòÉΓòÉΓòÉ 8.16. RxCloseMuxWaitSem - Close a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1354.  
  1355. This function closes a muxwait semaphore 
  1356.  
  1357. Syntax:
  1358.  
  1359.   muxrc = RxCloseMuxWaitSem( hmux )
  1360.  
  1361. where
  1362.  
  1363.   hmux  = existing muxwait semaphore handle
  1364.   muxrc = return code from DosCloseMuxWaitSem
  1365.  
  1366.  
  1367. ΓòÉΓòÉΓòÉ 8.17. RxDeleteMuxWaitSem - Delete from a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1368.  
  1369. This function deletes a semaphore from a muxwait semaphore list 
  1370.  
  1371. Syntax:
  1372.  
  1373.   muxrc = RxDeleteMuxWaitSem( hmux, hsem )
  1374.  
  1375. where
  1376.  
  1377.   hmux  = existing muxwait semaphore handle
  1378.   hsem  = handle of a semaphore in the muxwait semaphore list
  1379.   muxrc = return code from DosDeleteMuxWaitSem
  1380.  
  1381.  
  1382. ΓòÉΓòÉΓòÉ 8.18. RxAddMuxWaitSem - Add to a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1383.  
  1384. This function adds a semaphore to a muxwait semaphore list 
  1385.  
  1386. Syntax:
  1387.  
  1388.   muxrc = RxAddMuxWaitSem( hmux, hsem, semid )
  1389.  
  1390. where
  1391.  
  1392.   hmux  = existing muxwait semaphore handle
  1393.   hsem  = handle of a semaphore to add to the muxwait semaphore list
  1394.   semid = decimal integer used as an Id for this semaphore
  1395.   muxrc = return code from DosAddMuxWaitSem
  1396.  
  1397.  
  1398. ΓòÉΓòÉΓòÉ 8.19. RxQueryMuxWaitSem - Query a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1399.  
  1400. This function queries information about a muxwait semaphore 
  1401.  
  1402. Syntax:
  1403.  
  1404.   muxinfo = RxQueryMuxWaitSem( hmux, stemname )
  1405.  
  1406. where
  1407.  
  1408.   hmux     = existing muxwait semaphore handle
  1409.   stemname = a Rexx stem name (ending in a period '.'), under which is
  1410.              returned information about the muxwait semaphore.  The structure
  1411.              of the returned information is:
  1412.              1) stem.0   = a decimal integer indicating how many semaphores
  1413.                            are listed in this muxwait semaphore
  1414.              2) stem.n.1 = handle of Nth semaphore
  1415.              3) stem.n.2 = decimal integer Id of Nth semaphore
  1416.   muxinfo  = Two blank delimited tokens:
  1417.              1) return code from DosQueryMuxWaitSem
  1418.              2) a string of letters indicating this muxwait semaphore's
  1419.                 properties:
  1420.                 'S' if it's shared
  1421.                 'Y' if it's a wait ANY
  1422.                 'L' if it's a wait ALL
  1423.  
  1424.  
  1425. ΓòÉΓòÉΓòÉ 8.20. RxWaitMuxWaitSem - Wait on a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1426.  
  1427. This function waits on a muxwait semaphore 
  1428.  
  1429. Syntax:
  1430.  
  1431.   muxinfo = RxWaitMuxWaitSem( hmux [,timeout] )
  1432.  
  1433. where
  1434.  
  1435.   hmux     = existing muxwait semaphore handle
  1436.   timeout  = either a decimal integer (miliseconds to block), or the word
  1437.             'Indefinite'
  1438.   muxinfo  = Two blank delimited tokens:
  1439.              1) return code from DosQueryMuxWaitSem
  1440.              2) semaphore-id of releaser of muxwait sem (for more info,
  1441.                 see details of DosWaitMuxWaitSem)
  1442.  
  1443.  
  1444. ΓòÉΓòÉΓòÉ 9. Rexx Macro Space Functions ΓòÉΓòÉΓòÉ
  1445.  
  1446. These functions allow Rexx programs to query and alter the Rexx MacroSpace. 
  1447.  
  1448.  
  1449. ΓòÉΓòÉΓòÉ 9.1. RxAddMacro - Add Entry to MacroSpace ΓòÉΓòÉΓòÉ
  1450.  
  1451. This function adds a Rexx program to the macrospace. 
  1452.  
  1453. Syntax:
  1454.  
  1455.   addrc = RxAddMacro(funcname, sourcefile [,order])
  1456.  
  1457. where
  1458.  
  1459.   funcname   = name for function in macrospace
  1460.   sourcefile = name of source file where Rexx source code exists
  1461.   order      = order in macrospace (Before or After)
  1462.  
  1463. Note:
  1464.  
  1465.   Returned value is return code from RexxAddMacro.
  1466.  
  1467.  
  1468. ΓòÉΓòÉΓòÉ 9.2. RxDropMacro - Drop Entry from MacroSpace ΓòÉΓòÉΓòÉ
  1469.  
  1470. This function drops a function from the macrospace. 
  1471.  
  1472. Syntax:
  1473.  
  1474.   droprc = RxDropMacro(funcname)
  1475.  
  1476. where
  1477.  
  1478.   funcname   = name of function in macrospace
  1479.  
  1480. Note:
  1481.  
  1482.   Returned value is return code from RexxDropMacro.
  1483.  
  1484.  
  1485. ΓòÉΓòÉΓòÉ 9.3. RxClearMacroSpace - Clear Entire MacroSpace ΓòÉΓòÉΓòÉ
  1486.  
  1487. This function clears all functions from the macro space.  Be careful when using 
  1488. this as it will affect all processes in the system. 
  1489.  
  1490. Syntax:
  1491.  
  1492.   clear_rc = RxClearMacroSpace()
  1493.  
  1494. Note:
  1495.  
  1496.   Returned value is return code from RexxClearMacroSpace.
  1497.  
  1498.  
  1499. ΓòÉΓòÉΓòÉ 9.4. RxSaveMacroSpace - Save Macro to File ΓòÉΓòÉΓòÉ
  1500.  
  1501. This function saves a macrospace function to a file. 
  1502.  
  1503. Syntax:
  1504.  
  1505.   saverc = RxSaveMacroSpace(funcname, macfile)
  1506.  
  1507. where
  1508.  
  1509.   funcname = name of function in macrospace
  1510.   macfile  = name of file in which to save macro
  1511.  
  1512. Note:
  1513.  
  1514.   Returned value is return code from RexxSaveMacroSpace.
  1515.  
  1516.  
  1517. ΓòÉΓòÉΓòÉ 9.5. RxLoadMacroSpace - Load a Macro from File ΓòÉΓòÉΓòÉ
  1518.  
  1519. This function loads a macrospace function from a file. 
  1520.  
  1521. Syntax:
  1522.  
  1523.   loadrc = RxLoadMacroSpace(funcname, macfile)
  1524.  
  1525. where
  1526.  
  1527.   funcname = name of function in macrospace
  1528.   macfile  = name of file in which to save macro
  1529.  
  1530. Note:
  1531.  
  1532.   Returned value is return code from RexxLoadMacroSpace.
  1533.  
  1534.  
  1535. ΓòÉΓòÉΓòÉ 9.6. RxQueryMacro - Query MacroSpace ΓòÉΓòÉΓòÉ
  1536.  
  1537. This function queries the existence/position of a macro in the macrospace. 
  1538.  
  1539. Syntax:
  1540.  
  1541.   qinfo = RxQueryMacro(funcname)
  1542.  
  1543. where
  1544.  
  1545.   funcname = name of function in macrospace
  1546.   qinfo    = blank-delimited tokens:
  1547.              1) return code from RexxQueryMacro
  1548.                 If #1 is zero, then:
  1549.                 2) Before/After/?
  1550.  
  1551. Note:
  1552.  
  1553.   If first token is not zero, no other information was returned.
  1554.  
  1555.  
  1556. ΓòÉΓòÉΓòÉ 9.7. RxReorderMacro - Reorder Macro Position ΓòÉΓòÉΓòÉ
  1557.  
  1558. This function reorders the position of a macro within the macrospace. 
  1559.  
  1560. Syntax:
  1561.  
  1562.   reorderrc = RxReorderMacro(funcname, position)
  1563.  
  1564. where
  1565.  
  1566.   funcname = name of function in macrospace
  1567.   position = relative position in macrospace (Before/After)
  1568.  
  1569. Note:
  1570.  
  1571.   Returned value is return code from RexxReorderMacro
  1572.  
  1573.  
  1574. ΓòÉΓòÉΓòÉ 10. Threads, Tasking, etc. ΓòÉΓòÉΓòÉ
  1575.  
  1576. These functions allow a Rexx program to start and control new threads and 
  1577. processes. 
  1578.  
  1579.  
  1580. ΓòÉΓòÉΓòÉ 10.1. RxExecPgm - Execute a program ΓòÉΓòÉΓòÉ
  1581.  
  1582. This function starts another program in the same session. 
  1583.  
  1584. Syntax:
  1585.  
  1586.   exrc = RxExecPgm(pgmname [, mode [,argstring]])
  1587.  
  1588. where
  1589.  
  1590.   pgmname   = name of .EXE file to execute
  1591.   mode      = 'S'ync, 'A'sync, async'R'esult, 'T'race, 'B'ackground, 'L'oad,
  1592.               asyncresult'D'b.
  1593.               Default is 'S'ync.
  1594.   argstring = arg string to pass to program
  1595.   exrc      = three blank-delimited tokens:
  1596.               1) return code from DosExecPgm
  1597.               2) termination code / process-id (for asynchronous)
  1598.               3) new program's return code
  1599.  
  1600.  
  1601. ΓòÉΓòÉΓòÉ 10.2. RxStartSession - Start Another Session ΓòÉΓòÉΓòÉ
  1602.  
  1603. This function starts a program in another OS/2 session. 
  1604.  
  1605. Syntax:
  1606.  
  1607.   strc = RxStartSession(pgmname [,args [,related [,fgbg [,title [,type
  1608.                         [,ctrl] ] ] ] ] ])
  1609.  
  1610. where
  1611.  
  1612.   pgmname   = name of .EXE file to execute
  1613.   args      = arg string to pass to program
  1614.   related   = Relation of started session to this session, can be:
  1615.               'I'ndependent or 'C'hild
  1616.   fgbg      = Foreground/Background option, can be:
  1617.               'F'oreground or 'B'ackground
  1618.   title     = Session title (defaults to program name)
  1619.   type      = Program type, can be:
  1620.               'D'efault, 'F'ullscreen, 'P'M, 'V'irtual-Dos,
  1621.               'W'indowed-Virtual-Dos, vi'O'-windowable
  1622.   ctrl      = Program control, can be:
  1623.               'V'isible, 'I'nvisible, ma'X'imized, mi'N'imized,
  1624.               no'A'utoclose
  1625.   strc      = if DosStartSession failed:
  1626.               - return code from DosStartSession followed by error info
  1627.               if DosStartSession got zero rc:
  1628.               - return code from DosStartSession Session-ID Process-ID
  1629.  
  1630.  
  1631. ΓòÉΓòÉΓòÉ 10.3. RxStartRexxSession - Start a Rexx program on another session ΓòÉΓòÉΓòÉ
  1632.  
  1633. This function starts a Rexx program in another OS/2 session. (The program 
  1634. "RXSRS.EXE" must be in your path in order to use this function) 
  1635.  
  1636. Syntax:
  1637.  
  1638.   strc = RxStartRexxSession(execname [,arg1] [,arg2] ... [,argn])
  1639.  
  1640. where
  1641.  
  1642.   execname = name of Rexx program to execute
  1643.                    or
  1644.              a '$' immediately preceding a source program string
  1645.                    or
  1646.              a '&' immediately preceding a tokenized program string
  1647.              (for more info about these, see "RxCallInStore" and
  1648.               "RxTokenize")
  1649.   arg1     = arguments 1-n for target Rexx program
  1650.   ...
  1651.   argn
  1652.   strc     = if DosStartSession failed:
  1653.              - return code from DosStartSession followed by error info
  1654.              if DosStartSession worked:
  1655.              - return code from DosStartSession Session-ID Process-ID
  1656.  
  1657.  
  1658. ΓòÉΓòÉΓòÉ 10.4. RxDetachRexxPgm - Detach a Rexx program ΓòÉΓòÉΓòÉ
  1659.  
  1660. This function starts a Rexx program in the detached OS/2 session. (The program 
  1661. "RXSRS.EXE" must be in your path in order to use this function) 
  1662.  
  1663. Syntax:
  1664.  
  1665.   dtrc = RxDetachRexxPgm(execname [,arg1] [,arg2] ... [,argn])
  1666.  
  1667. where
  1668.  
  1669.   execname = name of Rexx program to execute
  1670.                    or
  1671.              a '$' immediately preceding a source program string
  1672.                    or
  1673.              a '&' immediately preceding a tokenized program string
  1674.              (for more info about these, see "RxCallInStore" and
  1675.               "RxTokenize")
  1676.   arg1     = arguments 1-n for target Rexx program
  1677.   ...
  1678.   argn
  1679.   dtrc     = if DosExecPgm failed:
  1680.              - return code from DosExecPgm, followed by error info
  1681.              if DosExecPgm worked:
  1682.              - return code from DosExecPgm "codeTerminate" and "codeResult"
  1683.  
  1684.  
  1685. ΓòÉΓòÉΓòÉ 10.5. RxKillProcess - Kill an OS/2 Process ΓòÉΓòÉΓòÉ
  1686.  
  1687. This function kills an OS/2 process by process-id. 
  1688.  
  1689. Syntax:
  1690.  
  1691.   killrc = RxKillProcess(pid [, action])
  1692.  
  1693. where
  1694.  
  1695.   pid    = process-id (decimal integer)
  1696.   action = 'Process' or 'Tree' (default is 'Process')
  1697.   killrc = return code from DosKillProcess
  1698.  
  1699.  
  1700. ΓòÉΓòÉΓòÉ 10.6. RxCreateThread - Start new thread ΓòÉΓòÉΓòÉ
  1701.  
  1702. This function starts execution at a supplied entry point on a new thread. The 
  1703. entry point is any valid procedure address (e.g. obtained by a call to 
  1704. RxQueryProcAddr, etc.). 
  1705.  
  1706. Syntax:
  1707.  
  1708.   tid = RxCreateThread(procaddr [, dataptr [, linktype [, stacksize
  1709.                                 [, threadflag]]]])
  1710.  
  1711. where
  1712.  
  1713.   procaddr     = Procedure Address
  1714.   dataptr      = pointer to arguments
  1715.   linktype     = 'System' or 'Optlink'
  1716.                  If linktype is 'System', then args 4 and 5 are:
  1717.     stacksize  = stacksize for thread (default is 8192)
  1718.     threadflag = 'Immediate' or 'Suspend'
  1719.   tid          = thread-id of new thread
  1720.  
  1721. Note:
  1722.   Pointer to arguments is optional, but if supplied must be a valid pointer.
  1723.  
  1724.  
  1725. ΓòÉΓòÉΓòÉ 10.7. RxKillThread - Kill a thread ΓòÉΓòÉΓòÉ
  1726.  
  1727. This function kills a thread by thread-id. 
  1728.  
  1729. Syntax:
  1730.  
  1731.   killrc = RxKillThread(tid)
  1732.  
  1733. where
  1734.  
  1735.   tid    = thread-id
  1736.   killrc = return code from DosKillThread
  1737.  
  1738.  
  1739. ΓòÉΓòÉΓòÉ 10.8. RxSetPriority - Set the priority of processes or threads ΓòÉΓòÉΓòÉ
  1740.  
  1741. This function sets the priority of one or more process and/or threads. 
  1742.  
  1743. Syntax:
  1744.  
  1745.   setrc = RxSetPriority(scope,class,delta,id)
  1746.  
  1747. where
  1748.  
  1749.   scope = 'P'rocess (default)
  1750.           t'R'ee
  1751.           'T'hread
  1752.   class = 'N'ochange (default)
  1753.           'I'dletime
  1754.           'R'egular
  1755.           'T'imecritical
  1756.           foreground'S'erver
  1757.   delta = any integer from -31 to +31, or ma'X'imum, or mi'N'imum
  1758.   id    = a Process-Id, Thread-Id, or nothing, depending on value
  1759.           of "scope"
  1760.   setrc = return code from DosSetPriority
  1761.  
  1762.  
  1763. ΓòÉΓòÉΓòÉ 10.9. RxResumeThread - Resume thread execution ΓòÉΓòÉΓòÉ
  1764.  
  1765. This function causes a thread to resume execution 
  1766.  
  1767. Syntax:
  1768.  
  1769.   resrc = RxResumeThread(tid)
  1770.  
  1771. where
  1772.  
  1773.   tid   = thread-id
  1774.   resrc = return code from DosResumeThread
  1775.  
  1776.  
  1777. ΓòÉΓòÉΓòÉ 10.10. RxSuspendThread - Suspend thread execution ΓòÉΓòÉΓòÉ
  1778.  
  1779. This function causes a thread to suspend execution 
  1780.  
  1781. Syntax:
  1782.  
  1783.   susrc = RxSuspendThread(tid)
  1784.  
  1785. where
  1786.  
  1787.   tid   = thread-id
  1788.   susrc = return code from DosSuspendThread
  1789.  
  1790.  
  1791. ΓòÉΓòÉΓòÉ 10.11. RxCreateRexxThread - Rexx on another thread ΓòÉΓòÉΓòÉ
  1792.  
  1793. This function executes a Rexx program on another thread of the same process. 
  1794. The started Rexx program has a separate variable pool, and maintains its own 
  1795. "current Rexx queue", indpendently of the starting Rexx program.  But all other 
  1796. features of multi-threaded applications apply (i.e. shared file handles, etc.) 
  1797.  
  1798. Syntax:
  1799.  
  1800.   tid = RxCreateRexxThread(execname [,arg1 [,arg2 [, ...]]])
  1801.  
  1802. where
  1803.  
  1804.   execname = name of Rexx program to execute
  1805.                    or
  1806.              a '$' immediately preceding a source program string
  1807.                    or
  1808.              a '&' immediately preceding a tokenized program string
  1809.              (for more info about these, see "RxCallInStore" and
  1810.               "RxTokenize")
  1811.   arg1     = arguments to Rexx program (up to 19 possible)
  1812.   arg2
  1813.   ...
  1814.   tid      = Thread-Id of new thread
  1815.  
  1816. Note:
  1817.  
  1818.   Example of executing a program string:
  1819.  
  1820.     crlf = '0d0a'x
  1821.     str = '/* Rexx */'crlf
  1822.     str = str 'Do i=1 To Arg()'crlf
  1823.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  1824.     str = str 'End'crlf
  1825.     str = str||'1a'x       /* EOF marker */
  1826.     call rxcreaterexxthread '$'str, date(), time()
  1827.  
  1828.  
  1829. ΓòÉΓòÉΓòÉ 11. NETBIOS information ΓòÉΓòÉΓòÉ
  1830.  
  1831. These functions allow a Rexx program to access certain NETBIOS information. 
  1832.  
  1833.  
  1834. ΓòÉΓòÉΓòÉ 11.1. RxNbSessionStatus - NetBios Session Status ΓòÉΓòÉΓòÉ
  1835.  
  1836. This function gets NetBios session status information. 
  1837.  
  1838. Syntax:
  1839.  
  1840.   nbname = 'S$SQLDBSERVR1#DB'
  1841.  
  1842.   nbrc =  RxNbSessionStatus(nbname,'s.','r')
  1843.  
  1844. Note:
  1845.  
  1846.   Return code is from NETBIOS api.  Second argument is name of a Rexx stem
  1847.   variable under which results are returned as such:
  1848.  
  1849.     stem.0 = number of sessions reported on
  1850.       stem.n.1 = Local session number
  1851.       stem.n.2 = Session state
  1852.       stem.n.3 = Local name
  1853.       stem.n.4 = Remote name
  1854.       stem.n.5 = Number of receive commands pending
  1855.       stem.n.6 = Number of send commands pending
  1856.  
  1857.   Third argument may be supplied to have a NETBIOS "Reset" done before and
  1858.   after obtaining session status.
  1859.  
  1860.  
  1861. ΓòÉΓòÉΓòÉ 12. DLL Handling ΓòÉΓòÉΓòÉ
  1862.  
  1863. These functions allow a Rexx program to load and execute procedures with- in 
  1864. DLL's.  Also, certain information about DLL's can be obtained. 
  1865.  
  1866.  
  1867. ΓòÉΓòÉΓòÉ 12.1. RxLoadModule - Load a DLL ΓòÉΓòÉΓòÉ
  1868.  
  1869. This function loads a DLL, returning a module handle (or an error code). 
  1870.  
  1871. Syntax:
  1872.  
  1873.   dosrc = RxLoadModule(rexxvar, dllname)
  1874.  
  1875. where:
  1876.  
  1877.   rexxvar = name of rexx variable in which module handle is returned
  1878.   dllname = name of DLL to load
  1879.   dosrc   = return code from DosLoadModule
  1880.  
  1881.  
  1882. ΓòÉΓòÉΓòÉ 12.2. RxFreeModule - Free a DLL ΓòÉΓòÉΓòÉ
  1883.  
  1884. This function frees the DLL whose module handle is supplied. 
  1885.  
  1886. Syntax:
  1887.  
  1888.   dosrc = RxFreeModule(hmod)
  1889.  
  1890. where:
  1891.  
  1892.   hmod    = module handle
  1893.   dosrc   = return code from DosFreeModule
  1894.  
  1895.  
  1896. ΓòÉΓòÉΓòÉ 12.3. RxQueryModuleName - Get Module Name ΓòÉΓòÉΓòÉ
  1897.  
  1898. This function returns the name of a module, given the module handle. 
  1899.  
  1900. Syntax:
  1901.  
  1902.   dosrc = RxQueryModuleName(rexxvar,hmod)
  1903.  
  1904. where:
  1905.  
  1906.   rexxvar = name of rexx variable in which module name is returned
  1907.   hmod    = module handle of DLL
  1908.   dosrc   = return code from DosQueryModuleName
  1909.  
  1910.  
  1911. ΓòÉΓòÉΓòÉ 12.4. RxQueryModuleHandle - Get Module Handle ΓòÉΓòÉΓòÉ
  1912.  
  1913. This function returns the handle of a module, given the module's name. 
  1914.  
  1915. Syntax:
  1916.  
  1917.   dosrc = RxQueryModuleHandle(rexxvar,modname)
  1918.  
  1919. where:
  1920.  
  1921.   rexxvar = name of rexx variable in which module handle is returned
  1922.   modname = name of DLL
  1923.   dosrc   = return code from DosQueryModuleHandle
  1924.  
  1925.  
  1926. ΓòÉΓòÉΓòÉ 12.5. RxQueryProcType - Query Procedure Type ΓòÉΓòÉΓòÉ
  1927.  
  1928. This function returns the addressing mode (16/32 bit) of a procedure of a DLL. 
  1929. The procedure can be identified either by name, or ordinal number. 
  1930.  
  1931. Syntax:
  1932.  
  1933.   entryname = 'SQLEXEC'
  1934.   ordinal = 3
  1935.  
  1936.   procinfo = RxQueryProcType(hmod,procid)
  1937.   amode = RxQueryProcType(hmod,entryname)
  1938.  
  1939. where:
  1940.  
  1941.   hmod     = module handle
  1942.   procid   = procedure-id (either an ordinal, or a procedure name)
  1943.   procinfo = Two blank-delimited tokens:
  1944.              1) return code from DosQueryProcType
  1945.              2) either "16" or "32", indicating 16 or 32 bit
  1946.  
  1947.  
  1948. ΓòÉΓòÉΓòÉ 12.6. RxQueryProcAddr - Query Procedure Address ΓòÉΓòÉΓòÉ
  1949.  
  1950. This function returns the address of an entry point in a DLL.  This entry point 
  1951. can then be used in RxCallEntryPoint to call an entry point in a Loaded DLL. 
  1952.  
  1953. Syntax:
  1954.  
  1955.   entryname = 'SQLEXEC' /* Entry name */
  1956.               3         /* Entry ordinal */
  1957.  
  1958.   dosrc = RxQueryProcAddr(rexxvar,hmod,procid)
  1959.  
  1960. where:
  1961.  
  1962.   rexxvar = name of rexx variable in which procedure address is returned
  1963.   hmod    = module handle of DLL
  1964.   procid  = procedure-id (either an ordinal, or a procedure name)
  1965.  
  1966.  
  1967. ΓòÉΓòÉΓòÉ 12.7. RxCallEntryPoint - Call an entry point ΓòÉΓòÉΓòÉ
  1968.  
  1969. This function "calls" the code which begins at the ProcAddress supplied. This 
  1970. ProcAddress could be the address obtained by RxQueryProcAddr for the entry 
  1971. point of a DLL.  But, it can be any "legal" entry point address of any routine. 
  1972.  
  1973. Syntax:
  1974.  
  1975.   procrc = RxCallEntryPoint(procaddr [,arg1 [, arg2 [,...]]] )
  1976.  
  1977. where
  1978.  
  1979.   procaddr = proc-address (could be obtained from RxQueryProcAddr, etc.)
  1980.   parg1
  1981.   ...
  1982.   parg19   = up to 19 arguments.  If an argument is a valid pointer, the
  1983.              pointer will be passed.  If not, a copy of the argument's value
  1984.              will be passed by reference.  Either way, the procedure must be
  1985.              expecting a pointer for each argument.
  1986.   procrc   = return code from the procedure
  1987.  
  1988. Note:
  1989.   Linkage to the proc-address is type _System.
  1990.  
  1991.  
  1992. ΓòÉΓòÉΓòÉ 13. OS/2 Pipes ΓòÉΓòÉΓòÉ
  1993.  
  1994. An assortment of OS/2 pipe-related functions (not complete). 
  1995.  
  1996.  
  1997. ΓòÉΓòÉΓòÉ 13.1. RxCreateNPipe - Create a named pipe ΓòÉΓòÉΓòÉ
  1998.  
  1999. This function creates an OS/2 named pipe. 
  2000.  
  2001. Syntax:
  2002.  
  2003.   dosrc = RxCreateNPipe( rexxvar, pipename, openmode, pipemode,
  2004.                          instance_count, outbufsize, inbufsize,
  2005.                          timeout)
  2006.  
  2007. where
  2008.  
  2009.    rexxvar  = name of Rexx variable into which read/write handle is placed
  2010.    pipename = name of pipe
  2011.  
  2012.    OpenMode Values
  2013.      W    = WriteBehind
  2014.      w    = NoWriteBehind
  2015.      I    = Inherit
  2016.      i    = NoInherit
  2017.      N(n) = Access Inbound
  2018.      O(o) = Access Outbound
  2019.      D(d) = Access Duplex
  2020.  
  2021.    PipeMode Values
  2022.      W    = Wait
  2023.      w    = NoWait
  2024.      T    = Pipe Type "Byte"
  2025.      t    = Pipe Type "Message"
  2026.      R    = Readmode "Byte"
  2027.      r    = Readmode "Message"
  2028.  
  2029.    Instance_Count
  2030.      Integer
  2031.  
  2032.    Outbuf Size
  2033.      Integer
  2034.  
  2035.    Inbuf Size
  2036.      Integer
  2037.  
  2038.    Timeout
  2039.      Integer
  2040.  
  2041.   dosrc   = return code from DosCreateNPipe()
  2042.  
  2043.  
  2044. ΓòÉΓòÉΓòÉ 13.2. RxConnectNPipe - Connect to a named pipe ΓòÉΓòÉΓòÉ
  2045.  
  2046. This function connects to a named pipe 
  2047.  
  2048. Syntax:
  2049.  
  2050.   dosrc = RxConnectNPipe(hpipe)
  2051.  
  2052. where
  2053.  
  2054.    hpipe  = pipe handle
  2055.    dosrc  = return code from DosConnectNPipe()
  2056.  
  2057.  
  2058. ΓòÉΓòÉΓòÉ 13.3. RxDisConnectNPipe - Disconnect from a named pipe ΓòÉΓòÉΓòÉ
  2059.  
  2060. This function disconnects from a named pipe 
  2061.  
  2062. Syntax:
  2063.  
  2064.   dosrc = RxDisConnectNPipe(hpipe)
  2065.  
  2066. where
  2067.  
  2068.    hpipe  = pipe handle
  2069.    dosrc  = return code from DosDisConnectNPipe()
  2070.  
  2071.  
  2072. ΓòÉΓòÉΓòÉ 13.4. RxCreatePipe - Create an un-named pipe ΓòÉΓòÉΓòÉ
  2073.  
  2074. This function creates an OS/2 un-named pipe 
  2075.  
  2076. Syntax:
  2077.  
  2078.   dosrc = RxCreatePipe(rexxstem [,pipesize])
  2079.  
  2080. where
  2081.  
  2082.    rexxstem = name of Rexx stem variable under which read handle,
  2083.               write handle, and pipe size are returned as such:
  2084.               stem.1 = read handle
  2085.               stem.2 = write handle
  2086.               stem.3 = pipe size
  2087.    dosrc  = return code from DosCreatePipe()
  2088.  
  2089.  
  2090. ΓòÉΓòÉΓòÉ 13.5. RxDestroyPipe - Destroy an un-named pipe ΓòÉΓòÉΓòÉ
  2091.  
  2092. This function destroys an OS/2 un-named pipe 
  2093.  
  2094. Syntax:
  2095.  
  2096.   dosrc = RxDestroyPipe(hread,hwrite)
  2097.  
  2098. where
  2099.  
  2100.    hread  = read handle
  2101.    hwrite = write handle
  2102.    dosrc  = return codes from DosClose()
  2103.  
  2104.  
  2105. ΓòÉΓòÉΓòÉ 14. OS/2 Queues ΓòÉΓòÉΓòÉ
  2106.  
  2107. Most of the OS/2 queue APIs are implemented here. 
  2108.  
  2109.  
  2110. ΓòÉΓòÉΓòÉ 14.1. RxCreateQueue - Create an OS/2 queue. ΓòÉΓòÉΓòÉ
  2111.  
  2112. This function creates an OS/2 queue. 
  2113.  
  2114. Syntax:
  2115.  
  2116.   dosrc = RxCreateQueue(rexxvar, qname, qflags)
  2117.  
  2118. where
  2119.  
  2120.    rexxvar  = name of Rexx variable into which queue handle is placed
  2121.    qname    = name of OS/2 queue
  2122.    qflags   = flags for queue creation:
  2123.               F - Fifo
  2124.               L - Lifo
  2125.               P - Priority
  2126.               C - Convert Address
  2127.               N - No-convert Address
  2128.   dosrc   = return code from DosCreateQueue()
  2129.  
  2130.  
  2131. ΓòÉΓòÉΓòÉ 14.2. RxOpenQueue - Open an OS/2 queue ΓòÉΓòÉΓòÉ
  2132.  
  2133. This function opens an OS/2 queue 
  2134.  
  2135. Syntax:
  2136.  
  2137.   dosrc = RxOpenQueue(rexxstem,qname)
  2138.  
  2139. where
  2140.  
  2141.    rexxstem = name of Rexx stem, under which info is returned:
  2142.               stem.1 = queue-owner-pid (integer)
  2143.               stem.2 = queue handle
  2144.    qname    = name of queue to open
  2145.    dosrc    = return code from DosOpenQueue()
  2146.  
  2147.  
  2148. ΓòÉΓòÉΓòÉ 14.3. RxPeekQueue - Peek at an OS/2 queue ΓòÉΓòÉΓòÉ
  2149.  
  2150. This function peeks at an OS/2 queue without reading it 
  2151.  
  2152. Syntax:
  2153.  
  2154.   dosrc = RxPeekQueue(rexxstem,qhandle,elemcode,waitcode,semhandle)
  2155.  
  2156. where
  2157.  
  2158.    rexxstem  = name of Rexx stem, under which info is returned:
  2159.                stem.1 = data pointer (e.g. for use with RxStorage)
  2160.                stem.2 = data length (of that pointed to by stem.1)
  2161.                stem.3 = PID of process which enqueued element
  2162.                stem.4 = event code (RequestData.ulData)
  2163.                stem.5 = element code
  2164.                stem.6 = element priority
  2165.    qhandle   = handle to queue
  2166.    elemcode  = element code (integer)
  2167.    waitcode  = whether to wait for data in queue
  2168.                W = Wait
  2169.                N = Nowait
  2170.    semhandle = handle of semaphore
  2171.    dosrc     = return code from DosPeekQueue()
  2172.  
  2173.  
  2174. ΓòÉΓòÉΓòÉ 14.4. RxReadQueue - Read an OS/2 queue ΓòÉΓòÉΓòÉ
  2175.  
  2176. This function reads an element off an OS/2 
  2177.  
  2178. Syntax:
  2179.  
  2180.   dosrc = RxReadQueue(rexxstem,qhandle,elemcode,waitcode,semhandle)
  2181.  
  2182. where
  2183.  
  2184.    rexxstem  = name of Rexx stem, under which info is returned:
  2185.                stem.1 = data pointer (e.g. for use with RxStorage)
  2186.                stem.2 = data length (of that pointed to by stem.1)
  2187.                stem.3 = PID of process which enqueued element
  2188.                stem.4 = event code (RequestData.ulData)
  2189.                stem.5 = element priority
  2190.    qhandle   = handle to queue
  2191.    elemcode  = element code (integer)
  2192.    waitcode  = whether to wait for data in queue
  2193.                W = Wait
  2194.                N = Nowait
  2195.    semhandle = handle of semaphore
  2196.    dosrc     = return code from DosReadQueue()
  2197.  
  2198.  
  2199. ΓòÉΓòÉΓòÉ 14.5. RxWriteQueue - Write to an OS/2 queue ΓòÉΓòÉΓòÉ
  2200.  
  2201. This function writes an element to an OS/2 
  2202.  
  2203. Syntax:
  2204.  
  2205.   dosrc = RxWriteQueue(qhandle,pointer,length,reqdata,elemprty)
  2206.  
  2207. where
  2208.  
  2209.    qhandle   = handle to queue
  2210.    pointer   = whatever 32 bits you want to put on queue
  2211.    length    = integer length associated with "pointer"
  2212.    reqdata   = integer request data
  2213.    elemprtry = element priority, if this is a priority queue
  2214.    dosrc     = return code from DosWriteQueue()
  2215.  
  2216.  
  2217. ΓòÉΓòÉΓòÉ 14.6. RxPurgeQueue - Purge elements from OS/2 queue ΓòÉΓòÉΓòÉ
  2218.  
  2219. This function purges elements from an OS/2 queue 
  2220.  
  2221. Syntax:
  2222.  
  2223.   dosrc = RxPurgeQueue(qhandle)
  2224.  
  2225. where
  2226.  
  2227.    qhandle   = handle to queue
  2228.    dosrc     = return code from DosPurgeQueue()
  2229.  
  2230.  
  2231. ΓòÉΓòÉΓòÉ 14.7. RxQueryQueue - Query info about OS/2 queue ΓòÉΓòÉΓòÉ
  2232.  
  2233. This function returns information about an OS/2 queue 
  2234.  
  2235. Syntax:
  2236.  
  2237.   info = RxQueryQueue(qhandle)
  2238.  
  2239. where
  2240.  
  2241.    qhandle   = handle to queue
  2242.    info      = two blank delimited tokens:
  2243.                1) return code from DosQueryQueue()
  2244.                2) number of elements on queue (if (1) is zero)
  2245.  
  2246.  
  2247. ΓòÉΓòÉΓòÉ 14.8. RxCloseQueue - Close an OS/2 queue ΓòÉΓòÉΓòÉ
  2248.  
  2249. This function closes an OS/2 queue 
  2250.  
  2251. Syntax:
  2252.  
  2253.   dosrc = RxCloseQueue(qhandle)
  2254.  
  2255. where
  2256.  
  2257.    qhandle   = handle to queue
  2258.    dosrc     = return code from DosCloseQueue()
  2259.  
  2260.  
  2261. ΓòÉΓòÉΓòÉ 14.9. RxReadQueueStr - Read data from OS/2 queue ΓòÉΓòÉΓòÉ
  2262.  
  2263. This function returns the de-referenced contents of an OS/2 queue element. 
  2264. That is, it dequeues an element and returns the data pointed to by the dequeued 
  2265. element as the function result.  It first does a DosOpenQueue, then a 
  2266. DosReadQueue(wait), but does NOT do a DosCloseQueue. 
  2267.  
  2268. Syntax:
  2269.  
  2270.   datastr = RxReadQueueStr(qname)
  2271.  
  2272. where
  2273.  
  2274.    qname     = name of queue to read
  2275.    datastr   = data pointed to by dequeued pointer
  2276.  
  2277.  
  2278. ΓòÉΓòÉΓòÉ 15. I/O Related ΓòÉΓòÉΓòÉ
  2279.  
  2280. Miscellaneous functions related to I/O operations. 
  2281.  
  2282.  
  2283. ΓòÉΓòÉΓòÉ 15.1. RxOpen - Open a file ΓòÉΓòÉΓòÉ
  2284.  
  2285. This function opens a file. 
  2286.  
  2287. Syntax:
  2288.  
  2289.   dosrc = RxOpen(rexxstem, filename, openflag, openmode [,attr] [,size])
  2290.  
  2291. where
  2292.  
  2293.   rexxstem  = name of Rexx stem variable under which info is returned:
  2294.               stem.1 = file handle
  2295.               stem.2 = action taken:
  2296.                        Existed
  2297.                        Created
  2298.                        Truncated
  2299.   filename  = name of file/pipe/stream to open
  2300.   openflag  = flag indicating what to do if file exists:
  2301.               (case does not matter)
  2302.               N - fail if New
  2303.               C - Create if new
  2304.               E - fail if Exists
  2305.               O - Open if exists
  2306.               R - Replace if exists
  2307.   openmode  = how to open file, valid combinations of:
  2308.               (case DOES matter)
  2309.               D - Dasd
  2310.               T - write Through
  2311.               F - Fail on error
  2312.               C - no Cache
  2313.               S - Sequential
  2314.               R - Random
  2315.               M - random/sequential (Mixed)
  2316.               H - no inHerit
  2317.               b - (sharemode) deny read/write (both)
  2318.               w - (sharemode) deny write
  2319.               r - (sharemode) deny read
  2320.               n - (sharemode) deny none
  2321.               R - (accessmode) Read only
  2322.               W - (accessmode) Write only
  2323.               B - (accessmode) readwrite (Both)
  2324.   attr      = file attribute, valid combinations of:
  2325.               (only if open creates file)
  2326.               A - Archived
  2327.               D - Directory
  2328.               S - System
  2329.               H - Hidden
  2330.               R - Readonly
  2331.               N - Normal (default)
  2332.   size      = file size (only if open creates file)
  2333.   dosrc     = return code from DosOpen()
  2334.  
  2335.  
  2336. ΓòÉΓòÉΓòÉ 15.2. RxRead - Read from File Handle ΓòÉΓòÉΓòÉ
  2337.  
  2338. This function reads a character stream in from a file handle, rather than from 
  2339. a file name. 
  2340.  
  2341. Syntax:
  2342.  
  2343.   dosrc = RxRead( rexxvar, hfile [,length] )
  2344.  
  2345. where
  2346.  
  2347.   rexxvar = name of Rexx variable into which read data is placed
  2348.   hfile   = handle of file to be read from
  2349.   length  = number of bytes to read (defaults to zero)
  2350.   dosrc   = two blank-delimited words:
  2351.             1) return code from DosRead
  2352.             2) if (1) is zero, an integer indicating number of bytes
  2353.                read (should be same as length of rexx variable's
  2354.                value)
  2355.  
  2356.  
  2357. ΓòÉΓòÉΓòÉ 15.3. RxWrite - Write to File Handle ΓòÉΓòÉΓòÉ
  2358.  
  2359. This function writes a character stream out to a file handle, rather than from 
  2360. a file name. 
  2361.  
  2362. Syntax:
  2363.  
  2364.   dosrc = RxWrite( hfile , data )
  2365.  
  2366. where
  2367.  
  2368.   hfile = handle of file to be written to
  2369.   data  = data to be written to file
  2370.   dosrc   = two blank-delimited words:
  2371.             1) return code from DosWrite
  2372.             2) if (1) is zero, an integer indicating number of bytes
  2373.                written (may not be same as length of data supplied)
  2374.  
  2375.  
  2376. ΓòÉΓòÉΓòÉ 15.4. RxCloseH - Close a File Handle ΓòÉΓòÉΓòÉ
  2377.  
  2378. This function closes a file handle. 
  2379.  
  2380. Syntax:
  2381.  
  2382.   closerc = RxCloseH(hfile)
  2383.  
  2384. where
  2385.  
  2386.   hfile   = handle of file to be closed
  2387.   closerc = return code from DosClose
  2388.  
  2389.  
  2390. ΓòÉΓòÉΓòÉ 15.5. RxExecI - Read data into a Rexx queue or stem from a file ΓòÉΓòÉΓòÉ
  2391.  
  2392. This function reads (text) data into a Rexx queue or stem variable from a file. 
  2393. It is meant to be like EXECIO in TSO and VM, and can be used in a similar 
  2394. fashion for file input. 
  2395.  
  2396. Syntax:
  2397.  
  2398.   info = RxExecI([fname], [qtype], [name], [type])
  2399.  
  2400. where:
  2401.  
  2402.   fname  = name of file to be read from (default reads from stdin)
  2403.   qtype  = 'Lifo' or 'Fifo' (default is 'Fifo')
  2404.            determines how lines are read onto queue
  2405.            (ignored for stems)
  2406.   name   = name of Rexx queue from into which data is read (default uses
  2407.            current queue)
  2408.                or
  2409.            name of a Rexx stem variable under which data is to be mapped as
  2410.              stem.0 = number of lines (stem.1 - stem.n)
  2411.              stem.1
  2412.              stem.2
  2413.              ...
  2414.              stem.n
  2415.   type   = 'Queue' or 'Stem' (default is 'Queue')
  2416.            this tells whether arg 3 is a Rexx Queue name or a stem
  2417.            variable name
  2418.   info   = two blank delimited numbers:
  2419.            1) number of lines read
  2420.            2) total number of bytes read
  2421.  
  2422. Example:
  2423.  
  2424.   /* Read a text file into the Rexx stem 's.' */
  2425.   info = rxexeci('c:\config.sys',,'s.','s')
  2426.   parse var info lines bytes
  2427.   Say lines 'lines were read'
  2428.   Say bytes 'bytes were read'
  2429.  
  2430.  
  2431. ΓòÉΓòÉΓòÉ 15.6. RxExecO - Write data from a Rexx queue or stem to a file ΓòÉΓòÉΓòÉ
  2432.  
  2433. This function writes data from a Rexx queue or stem variable to a file.  It is 
  2434. meant to be like EXECIO in TSO and VM, and can be used in a similar fashion for 
  2435. file output. 
  2436.  
  2437. Syntax:
  2438.  
  2439.   info = RxExecO([fname], [action], [name], [type])
  2440.  
  2441. where:
  2442.  
  2443.   fname  = name of file to be written to (default sends to stdout)
  2444.   action = Replace or Append (default is 'Replace')
  2445.            replaces or appends to 'fname'
  2446.   name   = name of Rexx queue from which to get data (default uses
  2447.            current queue)
  2448.                or
  2449.            name of a Rexx stem variable under which data is mapped as
  2450.              stem.1
  2451.              stem.2
  2452.              ...
  2453.              stem.n
  2454.            Once an uninitialized value for 'stem.n' is encountered,
  2455.            i/o stops.
  2456.   type   = 'Queue' or 'Stem' (default is 'Queue')
  2457.            this tells whether arg 3 is a Rexx Queue name or a stem
  2458.            variable name
  2459.   info   = two blank delimited numbers:
  2460.            1) number of lines written
  2461.            2) total number of bytes written
  2462.  
  2463. Example:
  2464.  
  2465.   /* Write 100 lines from current queue to c:\junk.dat (replace file) */
  2466.   Do 100
  2467.     Queue i time('l')
  2468.   End
  2469.   info = rxexeco('c:\junk.dat','r')
  2470.   parse var info lines bytes
  2471.   Say lines 'lines were written'
  2472.   Say bytes 'bytes were written'
  2473.  
  2474.  
  2475. ΓòÉΓòÉΓòÉ 15.7. Rxrsoe2f - Redirect Std-Out/Err to File ΓòÉΓòÉΓòÉ
  2476.  
  2477. This function redirects Standard Out and Standard Error to a named file (or 
  2478. device name, such as "CON"). 
  2479.  
  2480. Syntax:
  2481.  
  2482.   Call Rxrsoe2f stream,opt
  2483.  
  2484. where:
  2485.  
  2486.   stream = name of file or device (e.g. 'con', 'nul', 'kbd', etc.)
  2487.            to which standard-out and standard-error are re-directed.
  2488.   opt    = either 'Append' or 'Replace' file/device
  2489.  
  2490.  
  2491. ΓòÉΓòÉΓòÉ 16. System-Info related ΓòÉΓòÉΓòÉ
  2492.  
  2493. Functions returning OS/2 system information. 
  2494.  
  2495.  
  2496. ΓòÉΓòÉΓòÉ 16.1. RxPstat - Get Process Status Information ΓòÉΓòÉΓòÉ
  2497.  
  2498. This function returns process status information (like PSTAT). 
  2499.  
  2500.  
  2501.   **************  THIS FUNCTION IS NOT STABLE RIGHT NOW  ***********
  2502.  
  2503. Syntax:
  2504.  
  2505.   procrc = RxPStat(stemname)
  2506.  
  2507. where:
  2508.  
  2509.   stemname = a Rexx stem variable name under which results are
  2510.              mapped as such:
  2511.  
  2512.                stem.P.0 = number of processes
  2513.                stem.P.n.1 = process-id
  2514.                stem.P.n.2 = parent process-id
  2515.                stem.P.n.3 = process type
  2516.                stem.P.n.4 = process status
  2517.                stem.P.n.5 = process session-id
  2518.                stem.P.n.6 = process module name
  2519.                stem.P.n.T = process thread count
  2520.                stem.P.n.T.m.1 = thread-id within process
  2521.                stem.P.n.T.m.2 = unique thread slot number
  2522.                stem.P.n.T.m.3 = sleep-id thread is sleeping on
  2523.                stem.P.n.T.m.4 = thread priority
  2524.                stem.P.n.T.m.5 = thread state
  2525.                stem.P.n.T.m.6 = thread system time
  2526.                stem.P.n.T.m.7 = thread user time
  2527.   procrc   = return code from DosQProcStatus
  2528.  
  2529. Example:
  2530.  
  2531.   prc = rxpstat('s.')
  2532.   Say 'There are' s.p.0 'processes running right now'
  2533.  
  2534.  
  2535. ΓòÉΓòÉΓòÉ 16.2. RxSetError - Set DosError settings ΓòÉΓòÉΓòÉ
  2536.  
  2537. This function allows you to turn HardError and Exception popup on or off.  This 
  2538. change takes effect for the process in which it is issued, no matter what the 
  2539. previous setting was, by whom, or on what thread. Presently, there is no way 
  2540. (that I know of) to query or "reset" these error settings. 
  2541.  
  2542. Syntax:
  2543.  
  2544.   dosrc = RxSetError(flag)
  2545.  
  2546. where:
  2547.  
  2548.   flag  = any combination of:
  2549.           'h' to disable HardError popup
  2550.           'H' to enable  HardError popup
  2551.           'e' to disable Exception popup
  2552.           'E' to enable  Exception popup
  2553.   dosrc = return code from DosError()
  2554.  
  2555. Example:
  2556.  
  2557.   Call rxseterror 'eh'  /* would suppress popups from both harderror */
  2558.                         /* and exception conditions */
  2559.  
  2560.  
  2561. ΓòÉΓòÉΓòÉ 16.3. RxReplaceModule - Replace an active .DLL or .EXE ΓòÉΓòÉΓòÉ
  2562.  
  2563. This function uses the OS/2 "DosReplaceModule()" API to replace an active .DLL 
  2564. or .EXE (i.e. such a module that is locked because it is currently in use). 
  2565.  
  2566. Syntax:
  2567.  
  2568.   dosrc = RxReplaceModule(oldmodname, newmodname, backupmodname)
  2569.  
  2570. where:
  2571.  
  2572.   oldmodname    = name of locked module
  2573.   newmodname    = name of new module to replace old one
  2574.   backupmodname = name of backup module for recoverability
  2575.   dosrc         = return code from DosReplaceModule()
  2576.  
  2577.  
  2578. ΓòÉΓòÉΓòÉ 16.4. RxExitList - Use DosExitList ΓòÉΓòÉΓòÉ
  2579.  
  2580. This function uses the OS/2 "DosExitList()" API to work with OS/2 Exit-Handlers 
  2581. (i.e. add/remove/exit).  For more information on this function, see the OS/2 
  2582. developer's reference for "DosExitList()". 
  2583.  
  2584. Syntax:
  2585.  
  2586.   dosrc = RxExitList(funcaddr [,action] [,order] )
  2587.  
  2588. where:
  2589.  
  2590.   funcaddr  = function pointer (e.g. obtained by RxQueryProcAddr())
  2591.   action    = Add, Remove, Exit
  2592.   order     = 1 byte value (0x00-0xff) indicating order for "Add"
  2593.   dosrc     = return code from DosExitList()
  2594.  
  2595.  
  2596. ΓòÉΓòÉΓòÉ 16.5. RxProcId - Get process' own PID and TID information ΓòÉΓòÉΓòÉ
  2597.  
  2598. This function returns the process-id, parent process-id, and thread-id of the 
  2599. current thread of the current process. 
  2600.  
  2601. Syntax:
  2602.  
  2603.   procinfo = rxprocid()
  2604.  
  2605. where:
  2606.  
  2607.   procinfo = three blank delimited integers:
  2608.              1) process-id
  2609.              2) parent process-id
  2610.              3) thread-id
  2611.  
  2612.  
  2613. ΓòÉΓòÉΓòÉ 16.6. RxGetInfoBlocks - Get information about current process/thread ΓòÉΓòÉΓòÉ
  2614.  
  2615. This function returns the various pieces of information which the 
  2616. DosGetInfoBlocks() function returns. 
  2617.  
  2618. Syntax:
  2619.  
  2620.   dosrc = RxGetInfoBlocks(rexxstem)
  2621.  
  2622. where:
  2623.  
  2624.   rexxstem = name of rexx stem under which information is returned as
  2625.              such:
  2626.  
  2627.              stem.P.1  = process-id
  2628.              stem.P.2  = parent process-id
  2629.              stem.P.3  = our .EXE's module handle
  2630.              stem.P.4  = pointer to command line string
  2631.              stem.P.5  = pointer to environment string
  2632.              stem.P.6  = process status bits
  2633.              stem.P.7  = process type code
  2634.  
  2635.              stem.T.1  = thread-id
  2636.              stem.T.2  = thread priority
  2637.              stem.T.3  = tib2 version
  2638.              stem.T.4  = MustComplete count
  2639.              stem.T.5  = MustComplete Force Flag
  2640.              stem.T.6  = tib version
  2641.              stem.T.7  = thread ordinal
  2642.              stem.T.8  = pointer to head of exception handler chain
  2643.              stem.T.9  = pointer to base of stack
  2644.              stem.T.10 = pointer to end of stack
  2645.  
  2646.   dosrc    = return code from DosGetInfoBlocks()
  2647.  
  2648. Note:
  2649.  
  2650.   for stem.P.4, stem.P.5, stem.T.9, and stem.T.10, you could use
  2651.   RxStorage() to get to the values at these addresses.
  2652.  
  2653.  
  2654. ΓòÉΓòÉΓòÉ 16.7. RxQueryAppType - Get information about an executable file ΓòÉΓòÉΓòÉ
  2655.  
  2656. This function returns information about the type of an executable file as 
  2657. indicated in that file's header. 
  2658.  
  2659. Syntax:
  2660.  
  2661.   info = RxQueryAppType(filename)
  2662.  
  2663. where:
  2664.  
  2665.   filename = name of executable file whose type you want to know
  2666.              (either fully qualified, or just name and will search
  2667.               path)
  2668.   info     = return code from DosQueryAppType, and if zero, followed
  2669.              by any combination of:
  2670.  
  2671.              N - NotSpecified
  2672.              w - NotWindowCompat
  2673.              W - WindowCompat
  2674.              A - WindowApi
  2675.              B - Bound
  2676.              L - DLL
  2677.              D - DOS
  2678.              Y - Physical Device Driver
  2679.              V - Virtual Device Driver
  2680.              P - Protected Memory DLL
  2681.              3 - 32 Bit
  2682.  
  2683.  
  2684. ΓòÉΓòÉΓòÉ 16.8. RxQuerySysInfo - Query OS/2 SysInfo ΓòÉΓòÉΓòÉ
  2685.  
  2686. This function returns live system information about OS/2 via the 
  2687. DosQuerySysInfo API. 
  2688.  
  2689. Syntax:
  2690.  
  2691.   rc = RxQuerySysInfo( stemname [,startidx [,endidx]])
  2692.  
  2693. where
  2694.  
  2695.   stemname = Rexx stem name, under which results are returned.  Each
  2696.              DosQuerySysInfo item is returned under the appropriate stem.n
  2697.              For instance, the call "call rxquerysysinfo('s.',3,5)" would
  2698.              set the rexx variables "s.3", "s.4", and "s.5".
  2699.   rc       = return code from DosQuerySysInfo()
  2700.   startidx = Default is 1
  2701.   endidx   = Default is 23
  2702.  
  2703.   Index values:
  2704.  
  2705.   1. Maximum length, in bytes, of a path name.
  2706.   2. Maximum number of text sessions.
  2707.   3. Maximum number of PM sessions.
  2708.   4. Maximum number of DOS sessions.
  2709.   5. Drive from which the system was started (1 means drive A,
  2710.      2 means drive B, and so on).
  2711.   6. Dynamic priority variation flag (0 means absolute priority,
  2712.      1 means dynamic priority).
  2713.   7. Maximum wait in seconds.
  2714.   8. Minimum time slice in milliseconds.
  2715.   9. Maximum time slice in milliseconds.
  2716.  10. Memory page size in bytes.  This value is 4096 for the 80386
  2717.      processor.
  2718.  11. Major version number.
  2719.  12. Minor version number.
  2720.  13. Revision letter.
  2721.  14. Value of a 32-bit, free-running millisecond counter.  This value
  2722.      is zero when the system is started.
  2723.  15. Low-order 32 bits of the time in seconds since January 1, 1970
  2724.      at 0:00:00.
  2725.  16. High-order 32 bits of the time in seconds since January 1, 1970
  2726.      at 0:00:00.
  2727.  17. Total number of pages of physical memory in the system.
  2728.      One page is 4KB.
  2729.  18. Total number of pages of resident memory in the system.
  2730.  19. Maximum number of pages of memory that can be allocated by all
  2731.      processes in the system.  This number is advisory and is not
  2732.      guaranteed, since system conditions change constantly.
  2733.  20. Maximum number of bytes of memory that this process can allocate
  2734.      in its private arena.  This number is advisory and is not
  2735.      guaranteed, since system conditions change constantly.
  2736.  21. Maximum number of bytes of memory that a process can allocate in
  2737.      the shared arena.  This number is advisory and is not guaranteed,
  2738.      since system conditions change constantly.
  2739.  22. Timer interval in tenths of a millisecond.
  2740.  23. Maximum length, in bytes, of one component in a path name.
  2741.  
  2742.  
  2743. ΓòÉΓòÉΓòÉ 17. PM / Wp related functions ΓòÉΓòÉΓòÉ
  2744.  
  2745. Functions related to PM or Workplace Shell Objects 
  2746.  
  2747.  
  2748. ΓòÉΓòÉΓòÉ 17.1. RxWinQueryObject - Query WP-Shell Object Handle ΓòÉΓòÉΓòÉ
  2749.  
  2750. This function returns the object handle of a WorkPlace Shell object. 
  2751.  
  2752. Syntax:
  2753.  
  2754.   hobj = RxWinQueryObject(objname)
  2755.  
  2756. where
  2757.  
  2758.   objname = name of WorkPlace Shell object
  2759.   hobj    = handle to object (or null string if not successful)
  2760.  
  2761.  
  2762. ΓòÉΓòÉΓòÉ 17.2. RxWinDestroyObject - Destroy a WP-Shell Object ΓòÉΓòÉΓòÉ
  2763.  
  2764. This function destroys a WorkPlace Shell object by object handle. 
  2765.  
  2766. Syntax:
  2767.  
  2768.   yorn = RxWinDestroyObject(hobj)
  2769.  
  2770. where
  2771.  
  2772.   hobj    = handle to object
  2773.   yorn    = "1" if it worked, "0" if it didn't
  2774.